From 879f4fa041cfdefee655eb877f1a91f86a9c62b7 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Fri, 3 Mar 2017 00:56:40 -0800 Subject: New upstream version 5f2 --- scm.texi | 1542 ++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 940 insertions(+), 602 deletions(-) mode change 100644 => 100755 scm.texi (limited to 'scm.texi') diff --git a/scm.texi b/scm.texi old mode 100644 new mode 100755 index 3547f12..743881d --- a/scm.texi +++ b/scm.texi @@ -20,7 +20,7 @@ Copyright @copyright{} 1990-2007 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free @@ -84,9 +84,9 @@ The most recent information about SCM can be found on SCM's @dfn{WWW} home page: @ifset html - + @end ifset -@center @url{http://swiss.csail.mit.edu/~jaffer/SCM} +@center @url{http://people.csail.mit.edu/jaffer/SCM} @ifset html @end ifset @@ -153,7 +153,7 @@ timing information printed interactively (the @code{verbose} function). @section Authors @table @b -@item Aubrey Jaffer (agj @@ alum.mit.edu) +@item Aubrey Jaffer (agj@@alum.mit.edu) Most of SCM. @item Radey Shouman Arrays, @code{gsubr}s, compiled closures, records, Ecache, syntax-rules @@ -400,37 +400,119 @@ Documentation of the Xlib - SCM Language X Interface. @node Installing SCM, Operational Features, Overview, Top @chapter Installing SCM +SCM runs on a wide variety of platforms. ``Distributions'' is the +starting point for all platforms. The process described in ``GNU +configure and make'' will work on most Unix and GNU/Linux platforms. +If it works for you, then you may skip the later sections of +``Installing SCM''. + @menu -* Making SCM:: Bootstrapping. -* SLIB:: REQUIREd reading. +* Distributions:: Source and Binaries +* GNU configure and make:: For Unix and GNU/Linux * Building SCM:: -* Installing Dynamic Linking:: -* Configure Module Catalog:: -* Saving Images:: Make Fast-Booting Executables -* Automatic C Preprocessor Definitions:: -* Problems Compiling:: -* Problems Linking:: -* Problems Running:: -* Testing:: -* Reporting Problems:: +* Saving Executable Images:: For Faster Startup +* Installation:: +* Troubleshooting and Testing:: +@end menu + +@node Distributions, GNU configure and make, Installing SCM, Installing SCM +@section Distributions + +@noindent +The SCM homepage contains links to precompiled binaries and source +distributions. + +@noindent +Downloads and instructions for installing the precompiled binaries are +at @uref{http://people.csail.mit.edu/jaffer/SCM#QuickStart}. + +@noindent +If there is no precompiled binary for your platform, you may be able +to build from the source distribution. The rest of these instructions +deal with building and installing SCM and SLIB from sources. + +@noindent +Download (both SCM and SLIB of) either the last release or current +development snapshot from +@uref{http://people.csail.mit.edu/jaffer/SCM#BuildFromSource}. + +@noindent +Unzip both the SCM and SLIB zips. For example, if you are working in +@file{/usr/local/src/}, this will create directories +@file{/usr/local/src/scm/} and @file{/usr/local/src/slib/}. + + +@node GNU configure and make, Building SCM, Distributions, Installing SCM +@section GNU configure and make + +@file{scm/configure} and @file{slib/configure} are Shell scripts which +create the files @file{scm/config.status} and +@file{slib/config.status} on Unix and MinGW systems. + +The @file{config.status} files are used (included) by the Makefile to +control where the packages will be installed by @code{make install}. +With GNU shell (bash) and utilities, the following commands should +build and install SCM and SLIB: + +@example +bash$ (cd slib; ./configure --prefix=/usr/local/) +bash$ (cd scm +> ./configure --prefix=/usr/local/ +> make scmlit +> sudo make all +> sudo make install) +bash$ (cd slib; sudo make install) +@end example + +If the install commands worked, skip to @ref{Testing}. + +If @file{configure} doesn't work on your system, make +@file{scm/config.status} and @file{slib/config.status} be empty files. + +For additional help on using the @file{configure} script, run +@w{@samp{./configure --help}}. + +@samp{make all} will attempt to create a dumped executable +(@pxref{Saving Executable Images}), which has very small startup +latency. If that fails, it will try to compile an ordinary @samp{scm} +executable. + +Note that the compilation output may contain error messages; be +concerned only if the @samp{make install} transcripts contain errors. + +@samp{sudo} runs the command after it as user @dfn{root}. On recent +GNU/Linux systems, dumping requires that @samp{make all} be run as +user root; hence the use of @samp{sudo}. + +@samp{make install} requires root privileges if you are installing to +standard Unix locations as specified to (or defaulted by) +@samp{./configure}. Note that this is independent of whether you did +@w{@samp{sudo make all}} or @w{@samp{make all}}. + +@menu +* Making scmlit:: +* Makefile targets:: @end menu -@node Making SCM, SLIB, Installing SCM, Installing SCM -@section Making SCM +@node Making scmlit, Makefile targets, GNU configure and make, GNU configure and make +@subsection Making scmlit -The SCM distribution has @dfn{Makefile} which contains rules for -making @dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for -running @file{build}. @file{build} is used to compile (or create -scripts to compile) full featured versions (@pxref{Building SCM}). +@noindent +The SCM distribution @file{Makefile} contains rules for making +@dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for running +@file{build}. @file{build} is a Scheme program used to compile (or +create scripts to compile) full featured versions of SCM +(@pxref{Building SCM}). To create scmlit, run @w{@samp{make scmlit}} +in the @file{scm/} directory. -Makefiles are not portable to the majority of platforms. If -@file{Makefile} works for you, good; If not, I don't want to hear about -it. If you need to compile SCM without build, there are several ways to +@noindent +Makefiles are not portable to the majority of platforms. If you need +to compile SCM without @samp{scmlit}, there are several ways to proceed: @itemize @bullet @item -Use the @uref{http://swiss.csail.mit.edu/~jaffer/buildscm.html, build} +Use the @uref{http://people.csail.mit.edu/jaffer/buildscm.html, build} web page to create custom batch scripts for compiling SCM. @item @@ -445,48 +527,25 @@ script to build SCM; Create your own script or @file{Makefile}. @end itemize +@subheading Finding SLIB -@node SLIB, Building SCM, Making SCM, Installing SCM -@section SLIB +If you didn't create scmlit using @samp{make scmlit}, then you must +create a file named @file{scm/require.scm}. For most installations, +@file{scm/require.scm} can just be copied from +@file{scm/requires.scm}, which is part of the SCM distribution. @noindent -[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: +If, when executing @samp{scmlit} or @samp{scm}, you get a message +like: -@ifclear html -@itemize @bullet -@item -swiss.csail.mit.edu:/pub/scm/slib-3b1.tar.gz -@item -ftp.gnu.org:/pub/gnu/jacal/slib-3b1.tar.gz -@end itemize -@end ifclear - -@ifset html -@itemize @bullet -@item - -http://swiss.csail.mit.edu/ftpdir/scm/slib-3b1.zip - -@item - -ftp.gnu.org:/pub/gnu/jacal/slib-3b1.tar.gz - -@end itemize -@end ifset - -@noindent -Unpack SLIB (@samp{tar xzf slib-3b1.tar.gz} or @samp{unzip -ao -slib-3b1.zip}) in an appropriate directory for your system; both -@code{tar} and @code{unzip} will create the directory @file{slib}. +@example +ERROR: "LOAD couldn't find file " "/usr/local/src/scm/require" +@end example @noindent -Then create a file @file{require.scm} in the SCM +then create a file @file{require.scm} in the SCM @dfn{implementation-vicinity} (this is the same directory as where the -file @file{Init@value{SCMVERSION}.scm} is installed). +file @file{Init@value{SCMVERSION}.scm} is). @file{require.scm} should have the contents: @example @@ -494,12 +553,21 @@ file @file{Init@value{SCMVERSION}.scm} is installed). @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: +where the pathname string @file{/usr/local/lib/slib/} is to be +replaced by the pathname into which you unzipped (or installed) SLIB. + +@noindent +Alternatively, you can set the (shell) environment variable +@code{SCHEME_LIBRARY_PATH} to the pathname of the SLIB directory +(@pxref{SCM Variables, SCHEME_LIBRARY_PATH, Environment Variables}). +If set, this environment variable overrides @file{scm/require.scm}. + +@noindent +Absolute pathnames are recommended here; if you use a relative +pathname, SLIB can get confused when the working directory is changed +(@pxref{I/O-Extensions, chmod}). The way to specify a relative +pathname is to append it to the implementation-vicinity, which is +absolute: @example (define library-vicinity @@ -507,59 +575,204 @@ implementation-vicinity, which is absolute: (lambda () lv))) @end example + + +@node Makefile targets, , Making scmlit, GNU configure and make +@subsection Makefile targets + +Each of the following four @samp{make} targets creates an executable +named @file{scm}. Each target takes its build options from a file +with an @samp{.opt} suffix. If that options file doesn't exist, +making that target will create the file with the @samp{-F} features: +cautious, bignums, arrays, inexact, engineering-notation, and +dynamic-linking. Once that @samp{.opt} file exists, you can edit it +to your taste and it will be preserved. + +@table @code +@item make scm4 +Produces a R4RS executable named @file{scm} lacking hygienic macros +(but with defmacro). The build options are taken from +@file{scm4.opt}. If build or the executable fails, try removing +@samp{dynamic-linking} from @file{scm4.opt}. + +@item make scm5 +R5RS; like @samp{make scm4} but with @samp{-F macro}. The build +options are taken from @file{scm5.opt}. If build or the executable +fails, try removing @samp{dynamic-linking} from @file{scm5.opt}. + +@item make dscm4 +Produces a R4RS executable named @file{udscm4}, which it starts and +dumps to a low startup latency executable named @file{scm}. The build +options are taken from @file{udscm4.opt}. + +If the build fails, then @samp{build scm4} instead. If the dumped +executable fails to run, then send me a bug report (and use +@w{@samp{build scm4}} until the problem with dump is corrected). + +@item make dscm5 +Like @samp{make dscm4} but with @samp{-F macro}. The build options +are taken from @file{udscm5.opt}. + +If the build fails, then @samp{build scm5} instead. If the dumped +executable fails to run, then send me a bug report (and use +@w{@samp{build scm5}} until the problem with dump is corrected). + +@end table + @noindent -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. +If the above builds fail because of @w{@samp{-F dynamic-linking}}, +then (because they can't be dynamically linked) you will likely want +to add some other features to the build's @samp{.opt} file. See the +@samp{-F} build option in @ref{Build Options}. + +@noindent +If dynamic-linking is working, then you will likely want to compile +most of the modules as @dfn{DLL}s. The build options for compiling +DLLs are in @file{dlls.opt}. + +@table @code +@item make x.so +The @code{Xlib} module; +@ref{Top, ,SCM Language X Interface , Xlibscm, Xlibscm}. -@node Building SCM, Installing Dynamic Linking, SLIB, Installing SCM +@item make myturtle +Creates a DLL named @file{turtlegr.so} which is a simple graphics API. + +@item make wbscm.so +The @code{wb} module; +@ref{Top, ,B-tree database implementation , wb, wb}. +Compiling this requires that wb source be in a peer directory to scm. + +@item make dlls +Compiles all the distributed library modules, but not @file{wbscm.so}. +Many of the module compiles are recursively invoked in such a way that +failure of one (which could be due to a system library not being +installed) doesn't cause the top-level @samp{make dlls} to fail. If +@samp{make dlls} fails as a whole, it is time to submit a bug report +(@pxref{Reporting Problems}). + +@end table + + + +@node Building SCM, Saving Executable Images, GNU configure and make, Installing SCM @section Building SCM @cindex build @cindex build.scm -The file @dfn{build} loads the file @dfn{build.scm}, which constructs a -relational database of how to compile and link SCM executables. +The file @dfn{build} loads the file @dfn{build.scm}, which constructs +a relational database of how to compile and link SCM executables. @file{build.scm} has information for the platforms which SCM has been -ported to (of which I have been notified). Some of this information is -old, incorrect, or incomplete. Send corrections and additions to jaffer -@@ ai.mit.edu. +ported to (of which I have been notified). Some of this information +is old, incorrect, or incomplete. Send corrections and additions to +agj@@alum.mit.edu. @menu * Invoking Build:: -* Build Options:: +* Build Options:: build --help * Compiling and Linking Custom Files:: @end menu + @node Invoking Build, Build Options, Building SCM, Building SCM @subsection Invoking Build +This section teaches how to use @file{build}, a Scheme program for +creating compilation scripts to produce SCM executables and library +modules. The options accepted by @samp{build} are documented in +@ref{Build Options}. + @noindent -The @emph{all} method will also work for MS-DOS and unix. Use -the @emph{all} method if you encounter problems with @file{build}. +Use the @emph{any} method if you encounter problems with the other two +methods (MS-DOS, Unix). @table @asis @item MS-DOS From the SCM source directory, type @samp{build} followed by up to 9 command line arguments. -@item unix +@item Unix From the SCM source directory, type @samp{./build} followed by command line arguments. -@item @emph{all} +@item @emph{any} From the SCM source directory, start @samp{scm} or @samp{scmlit} and type @code{(load "build")}. Alternatively, start @samp{scm} or @samp{scmlit} with the command line argument @samp{-ilbuild}. +This method will also work for MS-DOS and Unix. + +After loading various SLIB modules, the program will print: + +@example +type (b "build ") to build +type (b*) to enter build command loop +@end example + +The @samp{b*} procedure enters into a @dfn{build shell} where you can +enter commands (with or without the @samp{build}). Blank lines are +ignored. To create a build script with all defaults type +@samp{build}. + +If the build-shell encouters an error, you can reenter the build-shell +by typing @samp{(b*)}. To exit scm type @samp{(quit)}. @end table @noindent -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. +Here is a transcript of an interactive (b*) build-shell. + +@example +bash$ scmlit +SCM version 5e7, Copyright (C) 1990-2006 Free Software Foundation. +SCM comes with ABSOLUTELY NO WARRANTY; for details type `(terms)'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `(terms)' for details. +> (load "build") +;loading build +; loading /home/jaffer/slib/getparam +; loading /home/jaffer/slib/coerce +... +; done loading build.scm +type (b "build ") to build +type (b*) to enter build command loop +;done loading build +# +> (b*) +;loading /home/jaffer/slib/comparse +;done loading /home/jaffer/slib/comparse.scm +build> -t exe +#! /bin/sh +# unix (linux) script created by SLIB/batch Wed Oct 26 17:14:23 2011 +# [-p linux] +# ================ Write file with C defines +rm -f scmflags.h +echo '#define IMPLINIT "Init5e7.scm"'>>scmflags.h +echo '#define BIGNUMS'>>scmflags.h +echo '#define FLOATS'>>scmflags.h +echo '#define ARRAYS'>>scmflags.h +# ================ Compile C source files +gcc -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c +# ================ Link C object files +gcc -rdynamic -o scm continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o -lm -lc +"scm" +build> -t exe -w myscript.sh +"scm" +build> (quit) +@end example + +@noindent +No compilation was done. The @samp{-t exe} command shows the compile +script. The @samp{-t exe -w myscript.sh} line creates a file +@file{myscript.sh} containing the compile script. To actually compile +and link it, type @samp{./myscript.sh}. + +@noindent +Invoking build without the @samp{-F} option will build or create a +shell script with the @code{arrays}, @code{inexact}, and +@code{bignums} options as defaults. Invoking @samp{build} with +@samp{-F lit -o scmlit} will make a script for compiling +@samp{scmlit}. @example bash$ ./build @@ -630,7 +843,7 @@ files: @table @file @item dlls.opt -Options for Makefile targets mydlls, myturtle, and x.so. +Options for Makefile targets dlls, myturtle, and x.so. @item gdb.opt Options for udgdbscm and gdbscm. @item libscm.opt @@ -833,119 +1046,8 @@ dynamic-loading), you can load the compiled file with the Scheme command add a compiled dll file to SLIB's catalog. -@node Installing Dynamic Linking, Configure Module Catalog, Building SCM, Installing SCM -@section Installing Dynamic Linking - -@noindent -Dynamic linking has not been ported to all platforms. Operating systems -in the BSD family (a.out binary format) can usually be ported to -@dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a -proposed POSIX standard and may be available on other machines with -@dfn{COFF} binary format. For notes about porting to MS-Windows and -finishing the port to VMS @ref{VMS Dynamic Linking}. - -@noindent -@dfn{DLD} is a library package of C functions that performs -@dfn{dynamic link editing} on GNU/Linux, VAX (Ultrix), Sun 3 (SunOS -3.4 and 4.0), SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and -Atari ST. It is available from: - -@ifclear html -@itemize @bullet -@item -ftp.gnu.org:pub/gnu/dld-3.3.tar.gz -@end itemize -@end ifclear - -@ifset html - -ftp.gnu.org:pub/gnu/dld-3.3.tar.gz - -@end ifset - -@noindent -These notes about using libdl on SunOS are from @file{gcc.info}: - -@quotation -On a Sun, linking using GNU CC fails to find a shared library and -reports that the library doesn't exist at all. - -This happens if you are using the GNU linker, because it does only -static linking and looks only for unshared libraries. If you have -a shared library with no unshared counterpart, the GNU linker -won't find anything. - -We hope to make a linker which supports Sun shared libraries, but -please don't ask when it will be finished--we don't know. - -Sun forgot to include a static version of @file{libdl.a} with some -versions of SunOS (mainly 4.1). This results in undefined symbols when -linking static binaries (that is, if you use @samp{-static}). If you -see undefined symbols @samp{_dlclose}, @samp{_dlsym} or @samp{_dlopen} -when linking, compile and link against the file -@file{mit/util/misc/dlsym.c} from the MIT version of X windows. -@end quotation - - -@node 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 +@node Saving Executable Images, Installation, Building SCM, Installing SCM +@section Saving Executable Images In SCM, the ability to save running program images is called @dfn{dump} (@pxref{Dump}). In order to make @code{dump} available to SCM, build @@ -962,7 +1064,8 @@ The @samp{dscm4} and @samp{dscm5} targets in the SCM @file{Makefile} save images from @file{udscm4} and @file{udscm5} executables respectively. -Recent GNU/Linux innovations interfere with @code{dump}. For: +@dfn{Address space layout randomization} interferes with @code{dump}. +Here are the fixes for various operating-systems: @table @asis @item Fedora-Core-1 @@ -970,7 +1073,7 @@ Remove the @samp{#} from the line @samp{#SETARCH = setarch i386} in the @file{Makefile}. @item Fedora-Core-3 -@url{http://jamesthornton.com/writing/emacs-compile.html} writes: +@url{http://jamesthornton.com/writing/emacs-compile.html} [For FC3] combreloc has become the default for recent GNU ld, which breaks the unexec/undump on all versions of both Emacs and XEmacs... @@ -978,8 +1081,8 @@ XEmacs... Override by adding the following to @file{udscm5.opt}: @samp{--linker-options="-z nocombreloc"} -@item Kernels later than 2.6.11 -@url{http://www.opensubscriber.com/message/emacs-devel@@gnu.org/1007118.html} +@item Linux Kernels later than 2.6.11 +@exdent @url{http://www.opensubscriber.com/message/emacs-devel@@gnu.org/1007118.html} mentions the @dfn{exec-shield} feature. Kernels later than 2.6.11 must do (as root): @@ -991,106 +1094,55 @@ before dumping. @file{Makefile} has this @file{randomize_va_space} stuffing scripted for targets @samp{dscm4} and @samp{dscm5}. You must either set @file{randomize_va_space} to 0 or run as root to dump. +@item OS-X 10.6 + +@exdent @url{http://developer.apple.com/library/mac/#documentation/Darwin/Reference/Manpages/man1/dyld.1.html} +The dynamic linker uses the following environment variables. They +affect any program that uses the dynamic linker. + +DYLD_NO_PIE + +Causes dyld to not randomize the load addresses of images in a process +where the main executable was built position independent. This can be +helpful when trying to reproduce and debug a problem in a PIE. + @end table -@node Automatic C Preprocessor Definitions, Problems Compiling, Saving Images, Installing SCM -@section Automatic C Preprocessor Definitions +@node Installation, Troubleshooting and Testing, Saving Executable Images, Installing SCM +@section Installation -These @samp{#defines} are automatically provided by preprocessors of -various C compilers. SCM uses the presence or absence of these -definitions to configure @dfn{include file} locations and aliases for -library functions. If the definition(s) corresponding to your system -type is missing as your system is configured, add @code{-D@var{flag}} to -the compilation command lines or add a @code{#define @var{flag}} line to -@file{scmfig.h} or the beginning of @file{scmfig.h}. +Once @code{scmlit}, @code{scm}, and @code{dlls} have been built, these +commands will install them to the locations specified when you ran +@samp{./configure}: @example -#define Platforms: -------- ---------- -ARM_ULIB Huw Rogers free unix library for acorn archimedes -AZTEC_C Aztec_C 5.2a -__CYGWIN__ Cygwin -__CYGWIN32__ Cygwin -_DCC Dice C on AMIGA -__GNUC__ Gnu CC (and DJGPP) -__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0 -__HIGHC__ MetaWare High C -__IBMC__ C-Set++ on OS/2 2.1 -_MSC_VER MS VisualC++ 4.2 -MWC Mark Williams C on COHERENT -__MWERKS__ Metrowerks Compiler; Macintosh and WIN32 (?) -_POSIX_SOURCE ?? -_QC Microsoft QuickC -__STDC__ ANSI C compliant -__TURBOC__ Turbo C and Borland C -__USE_POSIX ?? -__WATCOMC__ Watcom C on MS-DOS -__ZTC__ Zortech C +bash$ (cd scm; make install) +bash$ (cd slib; make install) +@end example -_AIX AIX operating system -__APPLE__ Apple Darwin -AMIGA SAS/C 5.10 or Dice C on AMIGA -__amigaos__ Gnu CC on AMIGA -atarist ATARI-ST under Gnu CC -__DragonflyBSD__ DragonflyBSD -__FreeBSD__ FreeBSD -GNUDOS DJGPP (obsolete in version 1.08) -__GO32__ DJGPP (future?) -hpux HP-UX -linux GNU/Linux -macintosh Macintosh (THINK_C and __MWERKS__ define) -MCH_AMIGA Aztec_c 5.2a on AMIGA -__MACH__ Apple Darwin -__MINGW32__ MinGW - Minimalist GNU for Windows -MSDOS Microsoft C 5.10 and 6.00A -_MSDOS Microsoft CLARM and CLTHUMB compilers. -__MSDOS__ Turbo C, Borland C, and DJGPP -__NetBSD__ NetBSD -nosve Control Data NOS/VE -__OpenBSD__ OpenBSD -SVR2 System V Revision 2. -sun SunOS -__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 and Cygwin (Win32 API) -_WIN32_WCE MS Windows CE -vms (and VMS) VAX-11 C under VMS. +Note that installation to system directories (like @samp{/usr/bin/}) +will require that those commands be run as root: -__alpha DEC Alpha processor -__alpha__ DEC Alpha processor -hp9000s800 HP RISC processor -__ia64 GCC on IA64 -__ia64__ GCC on IA64 -_LONGLONG GCC on IA64 -__i386__ DJGPP -i386 DJGPP -_M_ARM Microsoft CLARM compiler defines as 4 for ARM. -_M_ARMT Microsoft CLTHUMB compiler defines as 4 for Thumb. -MULTIMAX Encore computer -ppc PowerPC -__ppc__ PowerPC -pyr Pyramid 9810 processor -__sgi__ Silicon Graphics Inc. -sparc SPARC processor -sequent Sequent computer -tahoe CCI Tahoe processor -vax VAX processor -__x86_64 AMD Opteron +@example +bash$ (cd scm; sudo make install) +bash$ (cd slib; sudo make install) @end example +@node Troubleshooting and Testing, , Installation, Installing SCM +@section Troubleshooting and Testing + +@menu +* Problems Compiling:: +* Problems Linking:: +* Testing:: +* Problems Starting:: +* Problems Running:: +* Reporting Problems:: +@end menu -@node Problems Compiling, Problems Linking, Automatic C Preprocessor Definitions, Installing SCM -@section Problems Compiling +@node Problems Compiling, Problems Linking, Troubleshooting and Testing, Troubleshooting and Testing +@subsection Problems Compiling @multitable @columnfractions .10 .45 .45 @item FILE @@ -1144,8 +1196,8 @@ __x86_64 AMD Opteron @end multitable -@node Problems Linking, Problems Running, Problems Compiling, Installing SCM -@section Problems Linking +@node Problems Linking, Testing, Problems Compiling, Troubleshooting and Testing +@subsection Problems Linking @multitable @columnfractions .5 .5 @item PROBLEM @@ -1155,12 +1207,62 @@ __x86_64 AMD Opteron @end multitable -@node Problems Running, Testing, Problems Linking, Installing SCM -@section Problems Running +@node Testing, Problems Starting, Problems Linking, Troubleshooting and Testing +@subsection Testing + +@noindent +Loading @file{r4rstest.scm} in the distribution will run an [R4RS] +conformance test on @code{scm}. + +@example +> (load "r4rstest.scm") +@print{} +;loading r4rstest.scm +SECTION(2 1) +SECTION(3 4) + # + # + # + # +@dots{} +@end example + +@noindent +Loading @file{pi.scm} in the distribution will enable you to compute +digits of pi. + +@example +> (load "pi.scm") +;loading pi.scm +;done loading pi.scm +# +> (pi 100 5) +00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 +37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 +70679 +;Evaluation took 550 ms (60 in gc) 36976 cells work, 1548.B other +# +@end example + +@subheading Performance + +@noindent +Loading @file{bench.scm} will compute and display performance statistics +of SCM running @file{pi.scm}. @samp{make bench} or @samp{make benchlit} +appends the performance report to the file @file{BenchLog}, facilitating +tracking effects of changes to SCM on performance. + + +@node Problems Starting, Problems Running, Testing, Troubleshooting and Testing +@subsection Problems Starting @multitable @columnfractions .5 .5 @item PROBLEM @tab HOW TO FIX +@item /bin/bash: scm: program not found +@tab Is @samp{scm} in a @samp{$PATH} directory? +@item /bin/bash: /usr/local/bin/scm: Permission denied +@tab @code{chmod +x /usr/local/bin/scm} @item Opening message and then machine crashes. @tab Change memory model option to C compiler (or makefile). @item @@ -1194,49 +1296,8 @@ __x86_64 AMD Opteron @end multitable -@node Testing, Reporting Problems, Problems Running, Installing SCM -@section Testing - -@noindent -Loading @file{r4rstest.scm} in the distribution will run an [R4RS] -conformance test on @code{scm}. - -@example -> (load "r4rstest.scm") -@print{} -;loading "r4rstest.scm" -SECTION(2 1) -SECTION(3 4) - # - # - # - # -@dots{} -@end example - -@noindent -Loading @file{pi.scm} in the distribution will enable you to compute -digits of pi. - -@example -> (load "pi") -;loading "pi" -;done loading "pi.scm" -;Evaluation took 20 ms (0 in gc) 767 cells work, 233.B other -# -> (pi 100 5) -00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 -37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 -70679 -;Evaluation took 550 ms (60 in gc) 36976 cells work, 1548.B other -# -@end example - -@noindent -Loading @file{bench.scm} will compute and display performance statistics -of SCM running @file{pi.scm}. @samp{make bench} or @samp{make benchlit} -appends the performance report to the file @file{BenchLog}, facilitating -tracking effects of changes to SCM on performance. +@node Problems Running, Reporting Problems, Problems Starting, Troubleshooting and Testing +@subsection Problems Running @multitable @columnfractions .5 .5 @item PROBLEM @@ -1268,27 +1329,27 @@ tracking effects of changes to SCM on performance. @item VAX: botched longjmp. @end multitable -@table @asis -@item Sparc(SUN-4) heap is growing out of control -You are experiencing a GC problem peculiar to the Sparc. The problem -is that SCM doesn't know how to clear register windows. Every -location which is not reused still gets marked at GC time. This -causes lots of stuff which should be collected to not be. This will -be a problem with any @emph{conservative} GC until we find what -instruction will clear the register windows. This problem is -exacerbated by using lots of call-with-current-continuations. -A possible fix for dynthrow() is commented out in @file{continue.c}. -@end table +@c @table @asis +@c @item Sparc(SUN-4) heap is growing out of control +@c You are experiencing a GC problem peculiar to the Sparc. The problem +@c is that SCM doesn't know how to clear register windows. Every +@c location which is not reused still gets marked at GC time. This +@c causes lots of stuff which should be collected to not be. This will +@c be a problem with any @emph{conservative} GC until we find what +@c instruction will clear the register windows. This problem is +@c exacerbated by using lots of call-with-current-continuations. +@c A possible fix for dynthrow() is commented out in @file{continue.c}. +@c @end table -@node Reporting Problems, , Testing, Installing SCM -@section Reporting Problems +@node Reporting Problems, , Problems Running, Troubleshooting and Testing +@subsection Reporting Problems @noindent Reported problems and solutions are grouped under Compiling, Linking, -Running, and Testing. If you don't find your problem listed there, you -can send a bug report to @code{agj @@ alum.mit.edu}. The bug report -should include: +Running, and Testing. If you don't find your problem listed there, +you can send a bug report to @code{agj@@alum.mit.edu} or +@code{scm-discuss@@gnu.org}. The bug report should include: @enumerate @item @@ -1634,6 +1695,24 @@ terminal of the process, or #f if this information cannot be determined. For documentation of the procedures @code{getenv} and @code{system} @xref{System Interface, , , slib, SLIB}. +SCM extends @code{getenv} as suggested by draft SRFI-98: + +@defun getenv name +Looks up @var{name}, a string, in the program environment. If @var{name} is +found a string of its value is returned. Otherwise, @code{#f} is returned. +@end defun +@defun getenv +Returns names and values of all the environment variables as an +association-list. + +@example +(getenv) @result{} +(("PATH" . "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin") + ("USERNAME" . "taro")) +@end example +@end defun + + @defun vms-debug If SCM is compiled under VMS this @code{vms-debug} will invoke the VMS debugger. @@ -1647,8 +1726,8 @@ debugger. 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 +@end defun +@defun ed filename If SCM is compiled under VMS @code{ed} will invoke the editor with a single the single argument @var{filename}. @end defun @@ -1734,7 +1813,8 @@ 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 +@end defmac +@defmac trace With no arguments, makes sure that all the currently traced identifiers are traced (even if those identifiers have been redefined) and returns a list of the traced identifiers. @@ -1742,7 +1822,8 @@ list of the traced identifiers. @defmac untrace proc1 @dots{} Turns tracing off for its arguments. -@defmacx untrace +@end defmac +@defmac untrace With no arguments, untraces all currently traced identifiers and returns a list of these formerly traced identifiers. @end defmac @@ -1810,8 +1891,7 @@ offers source code debugging from GNU Emacs. PSD runs slowly, so start by instrumenting only a few functions at a time. @lisp -http://swiss.csail.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz -swiss.csail.mit.edu:/pub/scm/slib-psd1-3.tar.gz +http://groups.csail.mit.edu/mac/ftpdir/scm/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 @@ -2183,6 +2263,10 @@ Scans all of SCM objects and reclaims for further use those that are no longer accessible. @end defun +@defun gc #t +Garbage-collects only the ecache. +@end defun + @defun room @defunx room #t Prints out statistics about SCM's current use of storage. @code{(room #t)} @@ -2206,8 +2290,8 @@ by calling @code{execpath} with the pathname. 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 +@end defun +@defun execpath #f @defunx execpath newpath Sets the path to @code{#f} or @var{newpath}, respectively. The old path is returned. @@ -2345,7 +2429,7 @@ and MS-DOS. To implement this, I have written the MS-DOS programs: @cindex #! @cindex #!.bat which are available from: -@url{http://swiss.csail.mit.edu/ftpdir/scm/sharpbang.zip} +@url{http://groups.csail.mit.edu/mac/ftpdir/scm/sharpbang.zip} @noindent With these two programs installed in a @code{PATH} directory, we have @@ -2521,10 +2605,14 @@ Many of the optional features are supported as well. @itemx @code{exact->inexact} @itemx @code{inexact->exact} @xref{Numerical operations, , , r5rs, Revised(5) Scheme}. -@itemx @code{with-input-from-file} +@end table +@table @asis +@item @code{with-input-from-file} @itemx @code{with-output-to-file} @xref{Ports, , , r5rs, Revised(5) Scheme}. -@itemx @code{load} +@end table +@table @asis +@item @code{load} @itemx @code{transcript-on} @itemx @code{transcript-off} @xref{System interface, , , r5rs, Revised(5) Scheme}. @@ -2677,7 +2765,7 @@ seconds. Returns the integer time in internal time units from an unspecified starting time. The difference of two calls to @code{get-internal-real-time} divided by -@code{interal-time-units-per-second} will give elapsed real time in +@code{internal-time-units-per-second} will give elapsed real time in seconds. @end defun @@ -2930,8 +3018,8 @@ not open to a file the result is unspecified. Returns the current position of the character in @var{port} which will next be read or written. If @var{port} is open to a non-file then @code{#f} is returned. - -@defunx file-position port k +@end defun +@defun file-position port k Sets the current position in @var{port} which will next be read or written. If successful, @code{#f} is returned. If @var{port} is open to a non-file, then @code{file-position} returns @code{#f}. @@ -3321,8 +3409,8 @@ internal definitions) is a string, then that string is the @defun comment string1 @dots{} Appends @var{string1} @dots{} to the strings given as arguments to previous calls @code{comment}. - -@defunx comment +@end defun +@defun comment Returns the (appended) strings given as arguments to previous calls @code{comment} and empties the current string collection. @end defun @@ -3345,8 +3433,8 @@ read from. The value returned by this function will be the value of @code{#} in which case the expression will be treated as whitespace. @code{#} is the value returned by the expression @code{(if #f #f)}. - -@deffnx {Callback procedure} load:sharp c port +@end deffn +@deffn {Callback procedure} load:sharp c port Dispatches like @code{read:sharp}, but only during @code{load}s. The read-syntaxes handled by @code{load:sharp} are a superset of those handled by @code{read:sharp}. @code{load:sharp} calls @@ -4195,9 +4283,21 @@ The immediate integer closest to negative infinity. The ratio of the circumference to the diameter of a circle. @end defvr +These procedures are in addition to those in +@xref{Irrational Integer Functions, , , slib, SLIB}. + +@defun exact-round x +@defunx exact-floor x +@defunx exact-ceiling x +@defunx exact-truncate x +Return exact integers. +@end defun + @noindent These procedures augment the standard capabilities in @ref{Numerical operations, , ,r5rs, Revised(5) Scheme}. +Many are from +@xref{Irrational Real Functions, , , slib, SLIB}. @defun pi* z @code{(* pi @var{z})} @@ -4228,6 +4328,7 @@ Return the inverse hyperbolic sine, cosine, and tangent of @var{z} @defunx real-asin x @defunx real-acos x @defunx real-atan x +@defunx atan y x @defunx real-sinh x @defunx real-cosh x @@ -4255,6 +4356,12 @@ an error if the value which should be returned by a call to @code{real-expt} is not real. @end defun +@defun infinite? z +@defunx finite? z +All IEEE-754 numbers except positive and negative infinity and NaN +(non-a-number) are finite. +@end defun + @node Arrays, Records, Numeric, Packages @section Arrays @@ -4325,14 +4432,15 @@ an enclosed array will be @code{equal?} but will not in general be enclosed array is unspecified. examples: +@end defun + @example -(enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{} - # +@exdent (enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{} +@exdent # -(enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} - # +@exdent (enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} +@exdent # @end example -@end defun @defun array->list array Returns a list consisting of all the elements, in order, of @var{array}. @@ -4510,13 +4618,15 @@ Modifies @var{bv} by replacing each element with its negation. @end defun @defun bit-set*! bv uve bool -If uve is a bit-vector @var{bv} and uve must be of the same length. If -@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the -inversion of uve is AND'ed into @var{bv}. +If @var{uve} is a bit-vector, then @var{bv} and @var{uve} must be of +the same length. If @var{bool} is @code{#t}, then @var{uve} is OR'ed +into @var{bv}; If @var{bool} is @code{#f}, the inversion of @var{uve} +is AND'ed into @var{bv}. -If uve is a unsigned integer vector all the elements of uve must be -between 0 and the @code{LENGTH} of @var{bv}. The bits of @var{bv} -corresponding to the indexes in uve are set to @var{bool}. +If @var{uve} is a unsigned integer vector, then all the elements of +@var{uve} must be between 0 and the @code{LENGTH} of @var{bv}. The +bits of @var{bv} corresponding to the indexes in @var{uve} are set to +@var{bool}. The return value is unspecified. @end defun @@ -4718,12 +4828,12 @@ closed,, @code{closedir} returns a @code{#f}. each file in @var{directory}. The dynamic order in which @var{proc} is applied to the filenames is unspecified. The value returned by @samp{directory-for-each} is unspecified. - -@defunx directory-for-each proc directory pred +@end defun +@defun directory-for-each proc directory pred Applies @var{proc} only to those filenames for which the procedure @var{pred} returns a non-false value. - -@defunx directory-for-each proc directory match +@end defun +@defun directory-for-each proc directory match Applies @var{proc} only to those filenames for which @code{(filename:match?? @var{match})} would return a non-false value (@pxref{Filenames, , , slib, SLIB}). @@ -4741,6 +4851,16 @@ Applies @var{proc} only to those filenames for which @end example @end defun +@defun directory*-for-each proc path-glob +@var{path-glob} is a pathname whose last component is a (wildcard) pattern +(@pxref{Filenames, , , slib, SLIB}). +@var{proc} must be a procedure taking one argument. +@samp{directory*-for-each} applies @var{proc} to the (string) name of +each file in the current directory. The dynamic order in which @var{proc} is +applied to the filenames is unspecified. The value returned by +@samp{directory*-for-each} is unspecified. +@end defun + @defun mkdir path mode The @code{mkdir} function creates a new, empty directory whose name is @var{path}. The integer argument @var{mode} specifies the file @@ -4775,6 +4895,12 @@ If the renaming is successful, @code{#t} is returned. Otherwise, @code{#f} is returned. @end defun +@defun copy-file oldfilename newfilename +Copies the file specified by @var{oldfilename} to @var{newfilename}. +If the copying is successful, @code{#t} is returned. Otherwise, +@code{#f} is returned. +@end defun + @defun chmod file mode The function @code{chmod} sets the access permission bits for the file named by @var{file} to @var{mode}. The @var{file} argument may be a @@ -4843,8 +4969,8 @@ as @var{command}. If successful, this procedure does not return. Otherwise an error message is printed and the integer @code{errno} is returned. - -@defunx execv command arglist +@end defun +@defun execv command arglist @defunx execvp command arglist Like @code{execl} and @code{execlp} except that the set of arguments to @var{command} is @var{arglist}. @@ -5123,8 +5249,8 @@ or @code{#f}, indicating that the system default should be used. @defun setpwent #t Rewinds the pw entry table back to the begining. - -@defunx setpwent #f +@end defun +@defun setpwent #f @defunx setpwent Closes the pw table. @end defun @@ -5151,8 +5277,8 @@ A list of (string) names of users in the group. @defun setgrent #t Rewinds the group entry table back to the begining. - -@defunx setgrent #f +@end defun +@defun setgrent #f @defunx setgrent Closes the group table. @end defun @@ -5385,6 +5511,8 @@ to perform one substitution. @node Line Editing, Curses, Regular Expression Pattern Matching, Packages @section Line Editing +@code{(require 'edit-line)} + @noindent These procedures provide input line editing and recall. @@ -5414,9 +5542,9 @@ available from: @end itemize @noindent -When @file{Iedline.scm} is loaded, if the current input port is the -default input port and the environment variable @var{EMACS} is not -defined, line-editing mode will be entered. +When @code{edit-line} package is initialized, if the current input +port is the default input port and the environment variable +@var{EMACS} is not defined, line-editing mode will be entered. @defun default-input-port Returns the initial @code{current-input-port} SCM was invoked with @@ -5435,8 +5563,8 @@ retrieval of history. @defun line-editing Returns the current edited line port or @code{#f}. - -@defunx line-editing bool +@end defun +@defun line-editing bool If @var{bool} is false, exits line-editing mode and returns the previous value of @code{(line-editing)}. If @var{bool} is true, sets the current input and output ports to an edited line port and returns the previous @@ -6290,8 +6418,11 @@ in 2 basic flavors, Immediates and Cells: * Cells:: Non-Immediate types * Header Cells:: Malloc objects * Subr Cells:: Built-in and Compiled Procedures +* Defining Subrs:: * Ptob Cells:: I/O ports +* Defining Ptobs:: * Smob Cells:: Miscellaneous datatypes +* Defining Smobs:: * Data Type Representations:: How they all fit together @end menu @@ -6434,8 +6565,8 @@ The number of ispcsyms and ispcsyms+isyms, respectively. Defined in @code{letrec}, @code{or}, @code{quote}, @code{set!}, @code{#f}, @code{#t}, @code{#}, @code{#}, @code{()}, and @code{#}. - -@deftpx {CAR Immediate} ispcsym +@end deftp +@deftp {CAR Immediate} ispcsym special symbols: syntax-checked versions of first 14 isyms @end deftp @@ -6561,8 +6692,8 @@ Returns the C array of @code{SCM}s holding the elements of vector @deftp Header tc7_ssymbol static scheme symbol (part of initial system) - -@deftpx Header tc7_msymbol +@end deftp +@deftp Header tc7_msymbol @code{malloc}ed scheme symbol (can be GCed) @defmac SYMBOLP x @@ -6670,7 +6801,7 @@ Expands to the length of @var{cclo}. @end deftp -@node Subr Cells, Ptob Cells, Header Cells, Data Types +@node Subr Cells, Defining Subrs, Header Cells, Data Types @subsection Subr Cells @noindent @@ -6742,12 +6873,68 @@ argument is not present, @code{UNDEFINED} is passed in its place. C function of 2 arguments and a list of (rest of) @code{SCM} arguments. @end deftp -@deftp Subr tc7_lsubr -C function of list of @code{SCM} arguments. -@end deftp +@deftp Subr tc7_lsubr +C function of list of @code{SCM} arguments. +@end deftp + + +@node Defining Subrs, Ptob Cells, Subr Cells, Data Types +@subsection Defining Subrs + +@noindent +If @dfn{CCLO} is @code{#define}d when compiling, the compiled closure +feature will be enabled. It is automatically enabled if dynamic linking +is enabled. + +@noindent +The SCM interpreter directly recognizes subrs taking small numbers of +arguments. In order to create subrs taking larger numbers of arguments +use: + +@defun make_gsubr name req opt rest fcn +returns a cclo (compiled closure) object of name @code{char *} +@var{name} which takes @code{int} @var{req} required arguments, +@code{int} @var{opt} optional arguments, and a list of rest arguments if +@code{int} @var{rest} is 1 (0 for not). + +@code{SCM (*fcn)()} is a pointer to a C function to do the work. + +The C function will always be called with @var{req} + @var{opt} + +@var{rest} arguments, optional arguments not supplied will be passed +@code{UNDEFINED}. An error will be signaled if the subr is called with +too many or too few arguments. Currently a total of 10 arguments may be +specified, but increasing this limit should not be difficult. + +@example +/* A silly example, taking 2 required args, + 1 optional, and a list of rest args */ + +#include + +SCM gsubr_21l(req1,req2,opt,rst) + SCM req1,req2,opt,rst; +@{ + lputs("gsubr-2-1-l:\n req1: ", cur_outp); + display(req1,cur_outp); + lputs("\n req2: ", cur_outp); + display(req2,cur_outp); + lputs("\n opt: ", cur_outp); + display(opt,cur_outp); + lputs("\n rest: ", cur_outp); + display(rst,cur_outp); + newline(cur_outp); + return UNSPECIFIED; +@} + +void init_gsubr211() +@{ + make_gsubr("gsubr-2-1-l", 2, 1, 1, gsubr_21l); +@} +@end example +@end defun -@node Ptob Cells, Smob Cells, Subr Cells, Data Types +@node Ptob Cells, Defining Ptobs, Defining Subrs, Data Types @subsection Ptob Cells @noindent @@ -6820,7 +7007,40 @@ open output-port, respectively. @end defmac -@node Smob Cells, Data Type Representations, Ptob Cells, Data Types +@node Defining Ptobs, Smob Cells, Ptob Cells, Data Types +@subsection Defining Ptobs + +@noindent +@dfn{ptob}s are similar to smobs but define new types of port to which +SCM procedures can read or write. The following functions are defined +in the @code{ptobfuns}: + +@example +typedef struct @{ + SCM (*mark)P((SCM ptr)); + int (*free)P((FILE *p)); + int (*print)P((SCM exp, SCM port, int writing)); + SCM (*equalp)P((SCM, SCM)); + int (*fputc)P((int c, FILE *p)); + int (*fputs)P((char *s, FILE *p)); + sizet (*fwrite)P((char *s, sizet siz, sizet num, FILE *p)); + int (*fflush)P((FILE *stream)); + int (*fgetc)P((FILE *p)); + int (*fclose)P((FILE *p)); +@} ptobfuns; +@end example + +@noindent +The @code{.free} component to the structure takes a @code{FILE *} or +other C construct as its argument, unlike @code{.free} in a smob, which +takes the whole smob cell. Often, @code{.free} and @code{.fclose} can be +the same function. See @code{fptob} and @code{pipob} in @file{sys.c} +for examples of how to define ptobs. +Ptobs that must allocate blocks of memory should use, for example, +@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}. + + +@node Smob Cells, Defining Smobs, Defining Ptobs, Data Types @subsection Smob Cells @noindent @@ -6928,7 +7148,82 @@ VfixZ32, VfixN32, VfloR32, VfloR64, or VfloC64) in their @code{CDR}. @end deftp -@node Data Type Representations, , Smob Cells, Data Types +@node Defining Smobs, Data Type Representations, Smob Cells, Data Types +@subsection Defining Smobs + +@noindent +Here is an example of how to add a new type named @code{@i{foo}} to SCM. +The following lines need to be added to your code: + +@table @code +@item long tc16_@i{foo}; +The type code which will be used to identify the new type. +@item static smobfuns @i{foo}smob = @{mark@i{foo},free@i{foo},print@i{foo},equalp@i{foo}@}; +smobfuns is a structure composed of 4 functions: + +@example +typedef struct @{ + SCM (*mark)P((SCM)); + sizet (*free)P((CELLPTR)); + int (*print)P((SCM exp, SCM port, int writing)); + SCM (*equalp)P((SCM, SCM)); +@} smobfuns; +@end example + +@table @code +@item smob.mark +is a function of one argument of type @code{SCM} (the cell to mark) and +returns type @code{SCM} which will then be marked. If no further +objects need to be marked then return an immediate object such as +@code{BOOL_F}. The smob cell itself will already have been marked. +@emph{Note@:} This is different from SCM versions prior to 5c5. Only +additional data specific to a smob type need be marked by @code{smob.mark}. + + 2 functions are provided: + +@table @code +@item markcdr(ptr) +returns @code{CDR(ptr)}. +@item mark0(ptr) +is a no-op used for smobs containing no additional @code{SCM} data. 0 +may also be used in this case. +@end table + +@item smob.free +is a function of one argument of type @code{CELLPTR} (the cell to +collected) and returns type @code{sizet} which is the number of +@code{malloc}ed bytes which were freed. @code{Smob.free} should free +any @code{malloc}ed storage associated with this object. The function +free0(ptr) is provided which does not free any storage and returns 0. +@item smob.print +is 0 or a function of 3 arguments. The first, of type @code{SCM}, is +the smob object. The second, of type @code{SCM}, is the stream on which +to write the result. The third, of type int, is 1 if the object should +be @code{write}n, 0 if it should be @code{display}ed, and 2 if it should +be @code{write}n for an error report. This function should return non-zero +if it printed, and zero otherwise (in which case a hexadecimal number will +be printed). +@item smob.equalp +is 0 or a function of 2 @code{SCM} arguments. Both of these arguments +will be of type @code{tc16@i{foo}}. This function should return +@code{BOOL_T} if the smobs are equal, @code{BOOL_F} if they are not. If +@code{smob.equalp} is 0, @code{equal?} will return @code{BOOL_F} if they +are not @code{eq?}. +@end table + +@item tc16_@i{foo} = newsmob(&@i{foo}smob); +Allocates the new type with the functions from @code{@i{foo}smob}. This +line goes in an @code{init_} routine. +@end table + +@noindent +Promises and macros in @file{eval.c} and arbiters in @file{repl.c} +provide examples of SMOBs. There are a maximum of 256 SMOBs. +Smobs that must allocate blocks of memory should use, for example, +@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}. + + +@node Data Type Representations, , Defining Smobs, Data Types @subsection Data Type Representations @format @@ -6954,20 +7249,20 @@ ssymbol .........long length....G0000101 ..........char *chars........... msymbol .........long length....G0000111 ..........char *chars........... string .........long length....G0001101 ..........char *chars........... vector .........long length....G0001111 ...........SCM **elts........... -Vbool .........long length....G0010101 ..........long *words........... - spare 00010111 -VfixN8 .........long length....G0011101 ......unsigned char *words...... -VfixZ8 .........long length....G0011111 ..........char *words........... -VfixN16 .........long length....G0100101 ......unsigned short *words..... -VfixZ16 .........long length....G0100111 ........ short *words........... -VfixN32 .........long length....G0101101 ......unsigned long *words...... -VfixZ32 .........long length....G0101111 ..........long *words........... +VfixN8 .........long length....G0010101 ......unsigned char *words...... +VfixZ8 .........long length....G0010111 ..........char *words........... +VfixN16 .........long length....G0011101 ......unsigned short *words..... +VfixZ16 .........long length....G0011111 ........ short *words........... +VfixN32 .........long length....G0100101 ......unsigned medium *words.... +VfixZ32 .........long length....G0100111 ........medium *words........... +VfixN64 .........long length....G0101101 ......unsigned long *words...... +VfixZ64 .........long length....G0101111 ..........long *words........... VfloR32 .........long length....G0110101 .........float *words........... VfloC32 .........long length....G0110111 .........float *words........... VfloR64 .........long length....G0111101 ........double *words........... VfloC64 .........long length....G0111111 ........double *words........... - spare 01000101 +Vbool .........long length....G1000101 ..........long *words........... contin .........long length....G1001101 .............*regs.............. specfun ................xxxxxxxxG1001111 ...........SCM name............. cclo ..short length..xxxxxx10G1001111 ...........SCM **elts...........} @@ -7016,12 +7311,12 @@ array ...short rank..cxxxxxxxxG1111111 ............*array..............} @menu * Garbage Collection:: Automatically reclaims unused storage * Memory Management for Environments:: +* Dynamic Linking Support:: +* Configure Module Catalog:: +* Automatic C Preprocessor Definitions:: * Signals:: * C Macros:: * Changing Scm:: -* Defining Subrs:: -* Defining Smobs:: -* Defining Ptobs:: * Allocating memory:: * Embedding SCM:: In other programs * Callbacks:: @@ -7117,7 +7412,7 @@ object is freed. If the type header of smob is collected, the smob's @end deftypefun -@node Memory Management for Environments, Signals, Garbage Collection, Operations +@node Memory Management for Environments, Dynamic Linking Support, Garbage Collection, Operations @subsection Memory Management for Environments @ifset html @@ -7219,19 +7514,226 @@ and swept almost like any ordinary segment of the general purpose heap. The only difference is that pairs from the copying heap that become free during a sweep phase are not added to the freelist. -@cindex NO_ENV_CACHE -The environment cache is disabled by adding @code{#define NO_ENV_CACHE} -to @file{eval.c}; all environment cells are then allocated from the -regular heap. +@cindex NO_ENV_CACHE +The environment cache is disabled by adding @code{#define NO_ENV_CACHE} +to @file{eval.c}; all environment cells are then allocated from the +regular heap. + +@subsubheading Relation to Other Work + +This work seems to build upon a considerable amount of previous work +into garbage collection techniques about which a considerable amount +of literature is available. + + +@node Dynamic Linking Support, Configure Module Catalog, Memory Management for Environments, Operations +@subsection Dynamic Linking Support + +@noindent +Dynamic linking has not been ported to all platforms. Operating systems +in the BSD family (a.out binary format) can usually be ported to +@dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a +proposed POSIX standard and may be available on other machines with +@dfn{COFF} binary format. For notes about porting to MS-Windows and +finishing the port to VMS @ref{VMS Dynamic Linking}. + +@noindent +@dfn{DLD} is a library package of C functions that performs +@dfn{dynamic link editing} on GNU/Linux, VAX (Ultrix), Sun 3 (SunOS +3.4 and 4.0), SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and +Atari ST. It is available from: + +@ifclear html +@itemize @bullet +@item +ftp.gnu.org:pub/gnu/dld-3.3.tar.gz +@end itemize +@end ifclear + +@ifset html + +ftp.gnu.org:pub/gnu/dld-3.3.tar.gz + +@end ifset + +@noindent +These notes about using libdl on SunOS are from @file{gcc.info}: + +@quotation +On a Sun, linking using GNU CC fails to find a shared library and +reports that the library doesn't exist at all. + +This happens if you are using the GNU linker, because it does only +static linking and looks only for unshared libraries. If you have +a shared library with no unshared counterpart, the GNU linker +won't find anything. + +We hope to make a linker which supports Sun shared libraries, but +please don't ask when it will be finished--we don't know. + +Sun forgot to include a static version of @file{libdl.a} with some +versions of SunOS (mainly 4.1). This results in undefined symbols when +linking static binaries (that is, if you use @samp{-static}). If you +see undefined symbols @samp{_dlclose}, @samp{_dlsym} or @samp{_dlopen} +when linking, compile and link against the file +@file{mit/util/misc/dlsym.c} from the MIT version of X windows. +@end quotation + + +@node Configure Module Catalog, Automatic C Preprocessor Definitions, Dynamic Linking Support, Operations +@subsection 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 Automatic C Preprocessor Definitions, Signals, Configure Module Catalog, Operations +@subsection Automatic C Preprocessor Definitions + +These @samp{#defines} are automatically provided by preprocessors of +various C compilers. SCM uses the presence or absence of these +definitions to configure @dfn{include file} locations and aliases for +library functions. If the definition(s) corresponding to your system +type is missing as your system is configured, add @code{-D@var{flag}} to +the compilation command lines or add a @code{#define @var{flag}} line to +@file{scmfig.h} or the beginning of @file{scmfig.h}. + +@example +#define Platforms: +------- ---------- +ARM_ULIB Huw Rogers free unix library for acorn archimedes +AZTEC_C Aztec_C 5.2a +__CYGWIN__ Cygwin +__CYGWIN32__ Cygwin +_DCC Dice C on AMIGA +__GNUC__ Gnu CC (and DJGPP) +__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0 +__HIGHC__ MetaWare High C +__IBMC__ C-Set++ on OS/2 2.1 +_MSC_VER MS VisualC++ 4.2 +MWC Mark Williams C on COHERENT +__MWERKS__ Metrowerks Compiler; Macintosh and WIN32 (?) +_POSIX_SOURCE ?? +_QC Microsoft QuickC +__STDC__ ANSI C compliant +__TURBOC__ Turbo C and Borland C +__USE_POSIX ?? +__WATCOMC__ Watcom C on MS-DOS +__ZTC__ Zortech C -@subsubheading Relation to Other Work +_AIX AIX operating system +__APPLE__ Apple Darwin +AMIGA SAS/C 5.10 or Dice C on AMIGA +__amigaos__ Gnu CC on AMIGA +atarist ATARI-ST under Gnu CC +__DragonflyBSD__ DragonflyBSD +__FreeBSD__ FreeBSD +GNUDOS DJGPP (obsolete in version 1.08) +__GO32__ DJGPP (future?) +hpux HP-UX +linux GNU/Linux +macintosh Macintosh (THINK_C and __MWERKS__ define) +MCH_AMIGA Aztec_c 5.2a on AMIGA +__MACH__ Apple Darwin +__MINGW32__ MinGW - Minimalist GNU for Windows +MSDOS Microsoft C 5.10 and 6.00A +_MSDOS Microsoft CLARM and CLTHUMB compilers. +__MSDOS__ Turbo C, Borland C, and DJGPP +__NetBSD__ NetBSD +nosve Control Data NOS/VE +__OpenBSD__ OpenBSD +SVR2 System V Revision 2. +sun SunOS +__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 and Cygwin (Win32 API) +_WIN32_WCE MS Windows CE +vms (and VMS) VAX-11 C under VMS. -This work seems to build upon a considerable amount of previous work -into garbage collection techniques about which a considerable amount -of literature is available. +__alpha DEC Alpha processor +__alpha__ DEC Alpha processor +__hppa__ HP RISC processor +hp9000s800 HP RISC processor +__ia64 GCC on IA64 +__ia64__ GCC on IA64 +_LONGLONG GCC on IA64 +__i386__ DJGPP +i386 DJGPP +_M_ARM Microsoft CLARM compiler defines as 4 for ARM. +_M_ARMT Microsoft CLTHUMB compiler defines as 4 for Thumb. +MULTIMAX Encore computer +ppc PowerPC +__ppc__ PowerPC +pyr Pyramid 9810 processor +__sgi__ Silicon Graphics Inc. +sparc SPARC processor +sequent Sequent computer +tahoe CCI Tahoe processor +vax VAX processor +__x86_64 AMD Opteron +@end example -@node Signals, C Macros, Memory Management for Environments, Operations +@node Signals, C Macros, Automatic C Preprocessor Definitions, Operations @subsection Signals @cindex signals @@ -7262,8 +7764,8 @@ occurs during a time when @code{ints_disabled} is 1, then @code{deferred_proc} is set to non-zero, one of the global variables @code{SIGINT_deferred} or @code{SIGALRM_deferred} is set to 1, and the handler returns. - -@defmacx ALLOW_INTS +@end defmac +@defmac ALLOW_INTS Checks the deferred variables and if set the appropriate handler is called. @@ -7317,7 +7819,7 @@ a call to @code{wta(arg, pos, subr)}. @end defmac -@node Changing Scm, Defining Subrs, C Macros, Operations +@node Changing Scm, Allocating memory, C Macros, Operations @subsection Changing Scm @noindent @@ -7488,171 +7990,7 @@ New syntax can now be added without recompiling SCM by the use of the @xref{Syntax}. -@node Defining Subrs, Defining Smobs, Changing Scm, Operations -@subsection Defining Subrs - -@noindent -If @dfn{CCLO} is @code{#define}d when compiling, the compiled closure -feature will be enabled. It is automatically enabled if dynamic linking -is enabled. - -@noindent -The SCM interpreter directly recognizes subrs taking small numbers of -arguments. In order to create subrs taking larger numbers of arguments -use: - -@defun make_gsubr name req opt rest fcn -returns a cclo (compiled closure) object of name @code{char *} -@var{name} which takes @code{int} @var{req} required arguments, -@code{int} @var{opt} optional arguments, and a list of rest arguments if -@code{int} @var{rest} is 1 (0 for not). - -@code{SCM (*fcn)()} is a pointer to a C function to do the work. - -The C function will always be called with @var{req} + @var{opt} + -@var{rest} arguments, optional arguments not supplied will be passed -@code{UNDEFINED}. An error will be signaled if the subr is called with -too many or too few arguments. Currently a total of 10 arguments may be -specified, but increasing this limit should not be difficult. - -@example -/* A silly example, taking 2 required args, - 1 optional, and a list of rest args */ - -#include - -SCM gsubr_21l(req1,req2,opt,rst) - SCM req1,req2,opt,rst; -@{ - lputs("gsubr-2-1-l:\n req1: ", cur_outp); - display(req1,cur_outp); - lputs("\n req2: ", cur_outp); - display(req2,cur_outp); - lputs("\n opt: ", cur_outp); - display(opt,cur_outp); - lputs("\n rest: ", cur_outp); - display(rst,cur_outp); - newline(cur_outp); - return UNSPECIFIED; -@} - -void init_gsubr211() -@{ - make_gsubr("gsubr-2-1-l", 2, 1, 1, gsubr_21l); -@} -@end example -@end defun - - -@node Defining Smobs, Defining Ptobs, Defining Subrs, Operations -@subsection Defining Smobs - -@noindent -Here is an example of how to add a new type named @code{@i{foo}} to SCM. -The following lines need to be added to your code: - -@table @code -@item long tc16_@i{foo}; -The type code which will be used to identify the new type. -@item static smobfuns @i{foo}smob = @{mark@i{foo},free@i{foo},print@i{foo},equalp@i{foo}@}; -smobfuns is a structure composed of 4 functions: - -@example -typedef struct @{ - SCM (*mark)P((SCM)); - sizet (*free)P((CELLPTR)); - int (*print)P((SCM exp, SCM port, int writing)); - SCM (*equalp)P((SCM, SCM)); -@} smobfuns; -@end example - -@table @code -@item smob.mark -is a function of one argument of type @code{SCM} (the cell to mark) and -returns type @code{SCM} which will then be marked. If no further -objects need to be marked then return an immediate object such as -@code{BOOL_F}. The smob cell itself will already have been marked. -@emph{Note@:} This is different from SCM versions prior to 5c5. Only -additional data specific to a smob type need be marked by @code{smob.mark}. - - 2 functions are provided: - -@table @code -@item markcdr(ptr) -returns @code{CDR(ptr)}. -@item mark0(ptr) -is a no-op used for smobs containing no additional @code{SCM} data. 0 -may also be used in this case. -@end table - -@item smob.free -is a function of one argument of type @code{CELLPTR} (the cell to -collected) and returns type @code{sizet} which is the number of -@code{malloc}ed bytes which were freed. @code{Smob.free} should free -any @code{malloc}ed storage associated with this object. The function -free0(ptr) is provided which does not free any storage and returns 0. -@item smob.print -is 0 or a function of 3 arguments. The first, of type @code{SCM}, is -the smob object. The second, of type @code{SCM}, is the stream on which -to write the result. The third, of type int, is 1 if the object should -be @code{write}n, 0 if it should be @code{display}ed, and 2 if it should -be @code{write}n for an error report. This function should return non-zero -if it printed, and zero otherwise (in which case a hexadecimal number will -be printed). -@item smob.equalp -is 0 or a function of 2 @code{SCM} arguments. Both of these arguments -will be of type @code{tc16@i{foo}}. This function should return -@code{BOOL_T} if the smobs are equal, @code{BOOL_F} if they are not. If -@code{smob.equalp} is 0, @code{equal?} will return @code{BOOL_F} if they -are not @code{eq?}. -@end table - -@item tc16_@i{foo} = newsmob(&@i{foo}smob); -Allocates the new type with the functions from @code{@i{foo}smob}. This -line goes in an @code{init_} routine. -@end table - -@noindent -Promises and macros in @file{eval.c} and arbiters in @file{repl.c} -provide examples of SMOBs. There are a maximum of 256 SMOBs. -Smobs that must allocate blocks of memory should use, for example, -@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}. - - -@node Defining Ptobs, Allocating memory, Defining Smobs, Operations -@subsection Defining Ptobs - -@noindent -@dfn{ptob}s are similar to smobs but define new types of port to which -SCM procedures can read or write. The following functions are defined -in the @code{ptobfuns}: - -@example -typedef struct @{ - SCM (*mark)P((SCM ptr)); - int (*free)P((FILE *p)); - int (*print)P((SCM exp, SCM port, int writing)); - SCM (*equalp)P((SCM, SCM)); - int (*fputc)P((int c, FILE *p)); - int (*fputs)P((char *s, FILE *p)); - sizet (*fwrite)P((char *s, sizet siz, sizet num, FILE *p)); - int (*fflush)P((FILE *stream)); - int (*fgetc)P((FILE *p)); - int (*fclose)P((FILE *p)); -@} ptobfuns; -@end example - -@noindent -The @code{.free} component to the structure takes a @code{FILE *} or -other C construct as its argument, unlike @code{.free} in a smob, which -takes the whole smob cell. Often, @code{.free} and @code{.fclose} can be -the same function. See @code{fptob} and @code{pipob} in @file{sys.c} -for examples of how to define ptobs. -Ptobs that must allocate blocks of memory should use, for example, -@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}. - - -@node Allocating memory, Embedding SCM, Defining Ptobs, Operations +@node Allocating memory, Embedding SCM, Changing Scm, Operations @subsection Allocating memory SCM maintains a count of bytes allocated using malloc, and calls the garbage collector when that number exceeds a dynamically managed limit. @@ -8011,8 +8349,8 @@ any messages from error calls by @code{scm_addr}. @code{scm_addr} is useful for performing C operations on strings or other uniform arrays (@pxref{Uniform Array}). - -@deftypefunx unsigned long scm_base_addr(SCM @var{ra}, char *@var{s_name}) +@end deftypefun +@deftypefun unsigned long scm_base_addr(SCM @var{ra}, char *@var{s_name}) Returns a pointer (cast to an @code{unsigned long}) to the beginning of storage of array @var{ra}. Note that if @var{ra} is a shared-array, the strorage accessed this way may be much larger than -- cgit v1.2.3