aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rwxr-xr-x[-rw-r--r--]README996
1 files changed, 858 insertions, 138 deletions
diff --git a/README b/README
index e6d4e57..17d25f2 100644..100755
--- a/README
+++ b/README
@@ -1,10 +1,10 @@
-This directory contains the distribution of scm5e5. SCM conforms to
+This directory contains the distribution of scm5f2. SCM conforms to
Revised^5 Report on the Algorithmic Language Scheme and the IEEE P1178
specification. SCM runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2,
NOS/VE, Unicos, VMS, Unix and similar systems. SCM supports the SLIB
Scheme library; both SCM and SLIB are GNU packages.
- `http://swiss.csail.mit.edu/~jaffer/SCM'
+ `http://people.csail.mit.edu/jaffer/SCM'
0.1 Manifest
============
@@ -51,7 +51,7 @@ Scheme library; both SCM and SLIB are GNU packages.
functions.
`ioext.c' system calls in common between PC compilers and unix.
`lastfile.c' find the point in data space between data and libraries.
-`macos-config.h' Included by unexmacosx.c and lastfile.c.
+`macosx-config.h'Included by unexmacosx.c and lastfile.c.
`mkimpcat.scm' build SCM-specific catalog for SLIB.
`patchlvl.h' patchlevel of this release.
`pi.c' computes digits of pi [cc -o pi pi.c;time pi 100 5].
@@ -103,64 +103,99 @@ Scheme library; both SCM and SLIB are GNU packages.
-File: scm.info, Node: SLIB, Next: Building SCM, Prev: Making SCM, Up: Installing SCM
+File: scm-5f2.info, Node: Distributions, Next: GNU configure and make, Prev: Installing SCM, Up: Installing SCM
-2.2 SLIB
-========
+2.1 Distributions
+=================
-[SLIB] is a portable Scheme library meant to provide compatibility and
-utility functions for all standard Scheme implementations. Although
-SLIB is not _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:
+The SCM homepage contains links to precompiled binaries and source
+distributions.
- * swiss.csail.mit.edu:/pub/scm/slib-3b1.tar.gz
+Downloads and instructions for installing the precompiled binaries are
+at `http://people.csail.mit.edu/jaffer/SCM#QuickStart'.
- * ftp.gnu.org:/pub/gnu/jacal/slib-3b1.tar.gz
+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.
-Unpack SLIB (`tar xzf slib-3b1.tar.gz' or `unzip -ao slib-3b1.zip') in
-an appropriate directory for your system; both `tar' and `unzip' will
-create the directory `slib'.
+Download (both SCM and SLIB of) either the last release or current
+development snapshot from
+`http://people.csail.mit.edu/jaffer/SCM#BuildFromSource'.
-Then create a file `require.scm' in the SCM "implementation-vicinity"
-(this is the same directory as where the file `Init5e5.scm' is
-installed). `require.scm' should have the contents:
+Unzip both the SCM and SLIB zips. For example, if you are working in
+`/usr/local/src/', this will create directories `/usr/local/src/scm/'
+and `/usr/local/src/slib/'.
- (define (library-vicinity) "/usr/local/lib/slib/")
-where the pathname string `/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 (*note chmod: I/O-Extensions.).
-The way to specify a relative pathname is to append it to the
-implementation-vicinity, which is absolute:
- (define library-vicinity
- (let ((lv (string-append (implementation-vicinity) "../slib/")))
- (lambda () lv)))
+File: scm-5f2.info, Node: GNU configure and make, Next: Building SCM, Prev: Distributions, Up: Installing SCM
-Alternatively, you can set the (shell) environment variable
-`SCHEME_LIBRARY_PATH' to the pathname of the SLIB directory (*note
-SCHEME_LIBRARY_PATH: SCM Variables.). If set, the environment variable
-overrides `require.scm'. Again, absolute pathnames are recommended.
+2.2 GNU configure and make
+==========================
+
+`scm/configure' and `slib/configure' are Shell scripts which create the
+files `scm/config.status' and `slib/config.status' on Unix and MinGW
+systems.
+
+The `config.status' files are used (included) by the Makefile to
+control where the packages will be installed by `make install'. With
+GNU shell (bash) and utilities, the following commands should build and
+install SCM and SLIB:
+
+ 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)
+
+If the install commands worked, skip to *note Testing::.
+
+If `configure' doesn't work on your system, make `scm/config.status'
+and `slib/config.status' be empty files.
+
+For additional help on using the `configure' script, run
+`./configure --help'.
+
+`make all' will attempt to create a dumped executable (*note Saving
+Executable Images::), which has very small startup latency. If that
+fails, it will try to compile an ordinary `scm' executable.
+
+Note that the compilation output may contain error messages; be
+concerned only if the `make install' transcripts contain errors.
+
+`sudo' runs the command after it as user "root". On recent GNU/Linux
+systems, dumping requires that `make all' be run as user root; hence
+the use of `sudo'.
+`make install' requires root privileges if you are installing to
+standard Unix locations as specified to (or defaulted by)
+`./configure'. Note that this is independent of whether you did
+`sudo make all' or `make all'.
+* Menu:
-File: scm.info, Node: Making SCM, Next: SLIB, Prev: Installing SCM, Up: Installing SCM
+* Making scmlit::
+* Makefile targets::
-2.1 Making SCM
-==============
-The SCM distribution has "Makefile" which contains rules for making
-"scmlit", a "bare-bones" version of SCM sufficient for running `build'.
-`build' is used to compile (or create scripts to compile) full
-featured versions (*note Building SCM::).
-Makefiles are not portable to the majority of platforms. If `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 proceed:
+File: scm-5f2.info, Node: Making scmlit, Next: Makefile targets, Prev: GNU configure and make, Up: GNU configure and make
- * Use the build (http://swiss.csail.mit.edu/~jaffer/buildscm.html)
+2.2.1 Making scmlit
+-------------------
+
+The SCM distribution `Makefile' contains rules for making "scmlit", a
+"bare-bones" version of SCM sufficient for running `build'. `build' is
+a Scheme program used to compile (or create scripts to compile) full
+featured versions of SCM (*note Building SCM::). To create scmlit, run
+`make scmlit' in the `scm/' directory.
+
+Makefiles are not portable to the majority of platforms. If you need
+to compile SCM without `scmlit', there are several ways to proceed:
+
+ * Use the build (http://people.csail.mit.edu/jaffer/buildscm.html)
web page to create custom batch scripts for compiling SCM.
* Use SCM on a different platform to run `build' to create a script
@@ -171,61 +206,711 @@ need to compile SCM without build, there are several ways to proceed:
* Create your own script or `Makefile'.
+Finding SLIB
+------------
+If you didn't create scmlit using `make scmlit', then you must create a
+file named `scm/require.scm'. For most installations,
+`scm/require.scm' can just be copied from `scm/requires.scm', which is
+part of the SCM distribution.
-File: scm.info, Node: Editing Scheme Code, Next: Debugging Scheme Code, Prev: SCM Session, Up: Operational Features
+If, when executing `scmlit' or `scm', you get a message like:
-3.7 Editing Scheme Code
-=======================
+ ERROR: "LOAD couldn't find file " "/usr/local/src/scm/require"
- -- Function: ed arg1 ...
- The value of the environment variable `EDITOR' (or just `ed' if it
- isn't defined) is invoked as a command with arguments ARG1 ....
+then create a file `require.scm' in the SCM "implementation-vicinity"
+(this is the same directory as where the file `Init5f1.scm' is).
+`require.scm' should have the contents:
- -- Function: ed filename
- If SCM is compiled under VMS `ed' will invoke the editor with a
- single the single argument FILENAME.
+ (define (library-vicinity) "/usr/local/lib/slib/")
-Gnu Emacs:
- Editing of Scheme code is supported by emacs. Buffers holding
- files ending in .scm are automatically put into scheme-mode.
+where the pathname string `/usr/local/lib/slib/' is to be replaced by
+the pathname into which you unzipped (or installed) SLIB.
- If your Emacs can run a process in a buffer you can use the Emacs
- command `M-x run-scheme' with SCM. Otherwise, use the emacs
- command `M-x suspend-emacs'; or see "other systems" below.
+Alternatively, you can set the (shell) environment variable
+`SCHEME_LIBRARY_PATH' to the pathname of the SLIB directory (*note
+SCHEME_LIBRARY_PATH: SCM Variables.). If set, this environment
+variable overrides `scm/require.scm'.
-Epsilon (MS-DOS):
- There is lisp (and scheme) mode available by use of the package
- `LISP.E'. It offers several different indentation formats. With
- this package, buffers holding files ending in `.L', `.LSP', `.S',
- and `.SCM' (my modification) are automatically put into lisp-mode.
+Absolute pathnames are recommended here; if you use a relative
+pathname, SLIB can get confused when the working directory is changed
+(*note chmod: I/O-Extensions.). The way to specify a relative pathname
+is to append it to the implementation-vicinity, which is absolute:
- It is possible to run a process in a buffer under Epsilon. With
- Epsilon 5.0 the command line options `-e512 -m0' are neccessary to
- manage RAM properly. It has been reported that when compiling SCM
- with Turbo C, you need to `#define NOSETBUF' for proper operation
- in a process buffer with Epsilon 5.0.
+ (define library-vicinity
+ (let ((lv (string-append (implementation-vicinity) "../slib/")))
+ (lambda () lv)))
- One can also call out to an editor from SCM if RAM is at a
- premium; See "under other systems" below.
-other systems:
- Define the environment variable `EDITOR' to be the name of the
- editing program you use. The SCM procedure `(ed arg1 ...)' will
- invoke your editor and return to SCM when you exit the editor. The
- following definition is convenient:
- (define (e) (ed "work.scm") (load "work.scm"))
+File: scm-5f2.info, Node: Makefile targets, Prev: Making scmlit, Up: GNU configure and make
- Typing `(e)' will invoke the editor with the file of interest.
- After editing, the modified file will be loaded.
+2.2.2 Makefile targets
+----------------------
+
+Each of the following four `make' targets creates an executable named
+`scm'. Each target takes its build options from a file with an `.opt'
+suffix. If that options file doesn't exist, making that target will
+create the file with the `-F' features: cautious, bignums, arrays,
+inexact, engineering-notation, and dynamic-linking. Once that `.opt'
+file exists, you can edit it to your taste and it will be preserved.
+
+`make scm4'
+ Produces a R4RS executable named `scm' lacking hygienic macros
+ (but with defmacro). The build options are taken from `scm4.opt'.
+ If build or the executable fails, try removing `dynamic-linking'
+ from `scm4.opt'.
+
+`make scm5'
+ R5RS; like `make scm4' but with `-F macro'. The build options are
+ taken from `scm5.opt'. If build or the executable fails, try
+ removing `dynamic-linking' from `scm5.opt'.
+
+`make dscm4'
+ Produces a R4RS executable named `udscm4', which it starts and
+ dumps to a low startup latency executable named `scm'. The build
+ options are taken from `udscm4.opt'.
+
+ If the build fails, then `build scm4' instead. If the dumped
+ executable fails to run, then send me a bug report (and use
+ `build scm4' until the problem with dump is corrected).
+
+`make dscm5'
+ Like `make dscm4' but with `-F macro'. The build options are
+ taken from `udscm5.opt'.
+
+ If the build fails, then `build scm5' instead. If the dumped
+ executable fails to run, then send me a bug report (and use
+ `build scm5' until the problem with dump is corrected).
+
+
+If the above builds fail because of `-F dynamic-linking', then (because
+they can't be dynamically linked) you will likely want to add some
+other features to the build's `.opt' file. See the `-F' build option
+in *note Build Options::.
+
+If dynamic-linking is working, then you will likely want to compile
+most of the modules as "DLL"s. The build options for compiling DLLs
+are in `dlls.opt'.
+
+`make x.so'
+ The `Xlib' module; *note SCM Language X Interface: (Xlibscm)Top.
+
+`make myturtle'
+ Creates a DLL named `turtlegr.so' which is a simple graphics API.
+
+`make wbscm.so'
+ The `wb' module; *note B-tree database implementation: (wb)Top.
+ Compiling this requires that wb source be in a peer directory to
+ scm.
+
+`make dlls'
+ Compiles all the distributed library modules, but not `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 `make dlls' to fail.
+ If `make dlls' fails as a whole, it is time to submit a bug report
+ (*note Reporting Problems::).
+
+
+
+
+File: scm-5f2.info, Node: Building SCM, Next: Saving Executable Images, Prev: GNU configure and make, Up: Installing SCM
+
+2.3 Building SCM
+================
+
+The file "build" loads the file "build.scm", which constructs a
+relational database of how to compile and link SCM executables.
+`build.scm' has information for the platforms which SCM has been ported
+to (of which I have been notified). Some of this information is old,
+incorrect, or incomplete. Send corrections and additions to
+agj@alum.mit.edu.
+
+* Menu:
+
+* Invoking Build::
+* Build Options:: build --help
+* Compiling and Linking Custom Files::
+
+
+
+File: scm-5f2.info, Node: Invoking Build, Next: Build Options, Prev: Building SCM, Up: Building SCM
+
+2.3.1 Invoking Build
+--------------------
+
+This section teaches how to use `build', a Scheme program for creating
+compilation scripts to produce SCM executables and library modules.
+The options accepted by `build' are documented in *note Build Options::.
+
+Use the _any_ method if you encounter problems with the other two
+methods (MS-DOS, Unix).
+
+MS-DOS
+ From the SCM source directory, type `build' followed by up to 9
+ command line arguments.
+
+Unix
+ From the SCM source directory, type `./build' followed by command
+ line arguments.
+
+_any_
+ From the SCM source directory, start `scm' or `scmlit' and type
+ `(load "build")'. Alternatively, start `scm' or `scmlit' with the
+ command line argument `-ilbuild'. This method will also work for
+ MS-DOS and Unix.
+
+ After loading various SLIB modules, the program will print:
+
+ type (b "build <command-line>") to build
+ type (b*) to enter build command loop
+
+ The `b*' procedure enters into a "build shell" where you can enter
+ commands (with or without the `build'). Blank lines are ignored.
+ To create a build script with all defaults type `build'.
+
+ If the build-shell encouters an error, you can reenter the
+ build-shell by typing `(b*)'. To exit scm type `(quit)'.
+
+
+Here is a transcript of an interactive (b*) build-shell.
+
+ 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 <command-line>") to build
+ type (b*) to enter build command loop
+ ;done loading build
+ #<unspecified>
+ > (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)
+
+No compilation was done. The `-t exe' command shows the compile
+script. The `-t exe -w myscript.sh' line creates a file `myscript.sh'
+containing the compile script. To actually compile and link it, type
+`./myscript.sh'.
+
+Invoking build without the `-F' option will build or create a shell
+script with the `arrays', `inexact', and `bignums' options as defaults.
+Invoking `build' with `-F lit -o scmlit' will make a script for
+compiling `scmlit'.
+
+ bash$ ./build
+ -|
+ #! /bin/sh
+ # unix (linux) script created by SLIB/batch
+ # ================ Write file with C defines
+ rm -f scmflags.h
+ echo '#define IMPLINIT "Init5f1.scm"'>>scmflags.h
+ echo '#define BIGNUMS'>>scmflags.h
+ echo '#define FLOATS'>>scmflags.h
+ echo '#define ARRAYS'>>scmflags.h
+ # ================ Compile C source files
+ gcc -O2 -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c
+ # ================ Link C object files
+ gcc -rdynamic -o scm continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o -lm -lc
+
+To cross compile for another platform, invoke build with the `-p' or
+`--platform=' option. This will create a script for the platform named
+in the `-p' or `--platform=' option.
+
+ bash$ ./build -o scmlit -p darwin -F lit
+ -|
+ #! /bin/sh
+ # unix (darwin) script created by SLIB/batch
+ # ================ Write file with C defines
+ rm -f scmflags.h
+ echo '#define IMPLINIT "Init5f1.scm"'>>scmflags.h
+ # ================ Compile C source files
+ cc -O3 -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c
+ # ================ Link C object files
+ mv -f scmlit scmlit~
+ cc -o scmlit continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o
+
+
+
+File: scm-5f2.info, Node: Build Options, Next: Compiling and Linking Custom Files, Prev: Invoking Build, Up: Building SCM
+
+2.3.2 Build Options
+-------------------
+
+The options to "build" specify what, where, and how to build a SCM
+program or dynamically linked module. These options are unrelated to
+the SCM command line options.
+
+ -- Build Option: -p PLATFORM-NAME
+ -- Build Option: --platform=PLATFORM-NAME
+ specifies that the compilation should be for a
+ computer/operating-system combination called PLATFORM-NAME.
+ _Note_ The case of PLATFORM-NAME is distinguised. The current
+ PLATFORM-NAMEs are all lower-case.
+
+ The platforms defined by table "platform" in `build.scm' are:
+
+ Table: platform
+ name processor operating-system compiler
+ #f processor-family operating-system #f
+ symbol processor-family operating-system symbol
+ symbol symbol symbol symbol
+ ================= ================= ================= =================
+ *unknown* *unknown* unix cc
+ acorn-unixlib acorn *unknown* cc
+ aix powerpc aix cc
+ alpha-elf alpha unix cc
+ alpha-linux alpha linux gcc
+ amiga-aztec m68000 amiga cc
+ amiga-dice-c m68000 amiga dcc
+ amiga-gcc m68000 amiga gcc
+ amiga-sas m68000 amiga lc
+ atari-st-gcc m68000 atari-st gcc
+ atari-st-turbo-c m68000 atari-st tcc
+ borland-c i8086 ms-dos bcc
+ darwin powerpc unix cc
+ djgpp i386 ms-dos gcc
+ freebsd *unknown* unix cc
+ gcc *unknown* unix gcc
+ gnu-win32 i386 unix gcc
+ highc i386 ms-dos hc386
+ hp-ux hp-risc hp-ux cc
+ irix mips irix gcc
+ linux *unknown* linux gcc
+ linux-aout i386 linux gcc
+ linux-ia64 ia64 linux gcc
+ microsoft-c i8086 ms-dos cl
+ microsoft-c-nt i386 ms-dos cl
+ microsoft-quick-c i8086 ms-dos qcl
+ ms-dos i8086 ms-dos cc
+ netbsd *unknown* unix gcc
+ openbsd *unknown* unix gcc
+ os/2-cset i386 os/2 icc
+ os/2-emx i386 os/2 gcc
+ osf1 alpha unix cc
+ plan9-8 i386 plan9 8c
+ sunos sparc sunos cc
+ svr4 *unknown* unix cc
+ svr4-gcc-sun-ld sparc sunos gcc
+ turbo-c i8086 ms-dos tcc
+ unicos cray unicos cc
+ unix *unknown* unix cc
+ vms vax vms cc
+ vms-gcc vax vms gcc
+ watcom-9.0 i386 ms-dos wcc386p
+
+ -- Build Option: -f PATHNAME
+ specifies that the build options contained in PATHNAME be spliced
+ into the argument list at this point. The use of option files can
+ separate functional features from platform-specific ones.
+
+ The `Makefile' calls out builds with the options in `.opt' files:
+
+ `dlls.opt'
+ Options for Makefile targets dlls, myturtle, and x.so.
+
+ `gdb.opt'
+ Options for udgdbscm and gdbscm.
+
+ `libscm.opt'
+ Options for libscm.a.
+
+ `pg.opt'
+ Options for pgscm, which instruments C functions.
+
+ `udscm4.opt'
+ Options for targets udscm4 and dscm4 (scm).
+
+ `udscm5.opt'
+ Options for targets udscm5 and dscm5 (scm).
+
+ The Makefile creates options files it depends on only if they do
+ not already exist.
+
+ -- Build Option: -o FILENAME
+ -- Build Option: --outname=FILENAME
+ specifies that the compilation should produce an executable or
+ object name of FILENAME. The default is `scm'. Executable
+ suffixes will be added if neccessary, e.g. `scm' => `scm.exe'.
+
+ -- Build Option: -l LIBNAME ...
+ -- Build Option: --libraries=LIBNAME
+ specifies that the LIBNAME should be linked with the executable
+ produced. If compile flags or include directories (`-I') are
+ needed, they are automatically supplied for compilations. The `c'
+ library is always included. SCM "features" specify any libraries
+ they need; so you shouldn't need this option often.
+
+ -- Build Option: -D DEFINITION ...
+ -- Build Option: --defines=DEFINITION
+ specifies that the DEFINITION should be made in any C source
+ compilations. If compile flags or include directories (`-I') are
+ needed, they are automatically supplied for compilations. SCM
+ "features" specify any flags they need; so you shouldn't need this
+ option often.
+
+ -- Build Option: --compiler-options=FLAG
+ specifies that that FLAG will be put on compiler command-lines.
+
+ -- Build Option: --linker-options=FLAG
+ specifies that that FLAG will be put on linker command-lines.
+
+ -- Build Option: -s PATHNAME
+ -- Build Option: --scheme-initial=PATHNAME
+ specifies that PATHNAME should be the default location of the SCM
+ initialization file `Init5f1.scm'. SCM tries several likely
+ locations before resorting to PATHNAME (*note File-System
+ Habitat::). If not specified, the current directory (where build
+ is building) is used.
+
+ -- Build Option: -c PATHNAME ...
+ -- Build Option: --c-source-files=PATHNAME
+ specifies that the C source files PATHNAME ... are to be compiled.
+
+ -- Build Option: -j PATHNAME ...
+ -- Build Option: --object-files=PATHNAME
+ specifies that the object files PATHNAME ... are to be linked.
+
+ -- Build Option: -i CALL ...
+ -- Build Option: --initialization=CALL
+ specifies that the C functions CALL ... are to be invoked during
+ initialization.
+
+ -- Build Option: -t BUILD-WHAT
+ -- Build Option: --type=BUILD-WHAT
+ specifies in general terms what sort of thing to build. The
+ choices are:
+ `exe'
+ executable program.
+
+ `lib'
+ library module.
+
+ `dlls'
+ archived dynamically linked library object files.
+
+ `dll'
+ dynamically linked library object file.
+
+ The default is to build an executable.
+
+ -- Build Option: -h BATCH-SYNTAX
+ -- Build Option: -batch-dialect=BATCH-SYNTAX
+ specifies how to build. The default is to create a batch file for
+ the host system. The SLIB file `batch.scm' knows how to create
+ batch files for:
+ * unix
+
+ * dos
+
+ * vms
+
+ * amigaos (was amigados)
+
+ * system
+
+ This option executes the compilation and linking commands
+ through the use of the `system' procedure.
+
+ * *unknown*
+
+ This option outputs Scheme code.
+
+ -- Build Option: -w BATCH-FILENAME
+ -- Build Option: -script-name=BATCH-FILENAME
+ specifies where to write the build script. The default is to
+ display it on `(current-output-port)'.
+
+ -- Build Option: -F FEATURE ...
+ -- Build Option: --features=FEATURE
+ specifies to build the given features into the executable. The
+ defined features are:
+
+ "array"
+ Alias for ARRAYS
+
+ "array-for-each"
+ array-map! and array-for-each (arrays must also be featured).
+
+ "arrays"
+ Use if you want arrays, uniform-arrays and uniform-vectors.
+
+ "bignums"
+ Large precision integers.
+
+ "byte"
+ Treating strings as byte-vectors.
+
+ "byte-number"
+ Byte/number conversions
+
+ "careful-interrupt-masking"
+ Define this for extra checking of interrupt masking and some
+ simple checks for proper use of malloc and free. This is for
+ debugging C code in `sys.c', `eval.c', `repl.c' and makes the
+ interpreter several times slower than usual.
+
+ "cautious"
+ Normally, the number of arguments arguments to interpreted
+ closures (from LAMBDA) are checked if the function part of a
+ form is not a symbol or only the first time the form is
+ executed if the function part is a symbol. defining
+ `reckless' disables any checking. If you want to have SCM
+ always check the number of arguments to interpreted closures
+ define feature `cautious'.
+
+ "cheap-continuations"
+ If you only need straight stack continuations, executables
+ compile with this feature will run faster and use less
+ storage than not having it. Machines with unusual stacks
+ _need_ this. Also, if you incorporate new C code into scm
+ which uses VMS system services or library routines (which
+ need to unwind the stack in an ordrly manner) you may need to
+ use this feature.
+
+ "compiled-closure"
+ Use if you want to use compiled closures.
+
+ "curses"
+ For the "curses" screen management package.
+
+ "debug"
+ Turns on the features `cautious' and
+ `careful-interrupt-masking'; uses `-g' flags for debugging
+ SCM source code.
+
+ "differ"
+ Sequence comparison
+
+ "dont-memoize-locals"
+ SCM normally converts references to local variables to ILOCs,
+ which make programs run faster. If SCM is badly broken, try
+ using this option to disable the MEMOIZE_LOCALS feature.
+
+ "dump"
+ Convert a running scheme program into an executable file.
+ "dynamic-linking"
+ Be able to load compiled files while running.
+ "edit-line"
+ interface to the editline or GNU readline library.
-File: scm.info, Node: Problems Compiling, Next: Problems Linking, Prev: Automatic C Preprocessor Definitions, Up: Installing SCM
+ "engineering-notation"
+ Use if you want floats to display in engineering notation
+ (exponents always multiples of 3) instead of scientific
+ notation.
-2.8 Problems Compiling
-======================
+ "generalized-c-arguments"
+ `make_gsubr' for arbitrary (< 11) arguments to C functions.
+
+ "i/o-extensions"
+ Commonly available I/O extensions: "exec", line I/O, file
+ positioning, file delete and rename, and directory functions.
+
+ "inexact"
+ Use if you want floating point numbers.
+
+ "lit"
+ Lightweight - no features
+
+ "macro"
+ C level support for hygienic and referentially transparent
+ macros (syntax-rules macros).
+
+ "mysql"
+ Client connections to the mysql databases.
+
+ "no-heap-shrink"
+ Use if you want segments of unused heap to not be freed up
+ after garbage collection. This may increase time in GC for
+ *very* large working sets.
+
+ "none"
+ No features
+
+ "posix"
+ Posix functions available on all "Unix-like" systems. fork
+ and process functions, user and group IDs, file permissions,
+ and "link".
+
+ "reckless"
+ If your scheme code runs without any errors you can disable
+ almost all error checking by compiling all files with
+ `reckless'.
+
+ "record"
+ The Record package provides a facility for user to define
+ their own record data types. See SLIB for documentation.
+
+ "regex"
+ String regular expression matching.
+
+ "rev2-procedures"
+ These procedures were specified in the `Revised^2 Report on
+ Scheme' but not in `R4RS'.
+
+ "sicp"
+ Use if you want to run code from:
+
+ Harold Abelson and Gerald Jay Sussman with Julie Sussman.
+ `Structure and Interpretation of Computer Programs.' The MIT
+ Press, Cambridge, Massachusetts, USA, 1985.
+
+ Differences from R5RS are:
+ * (eq? '() '#f)
+
+ * (define a 25) returns the symbol a.
+
+ * (set! a 36) returns 36.
+
+ "single-precision-only"
+ Use if you want all inexact real numbers to be single
+ precision. This only has an effect if SINGLES is also
+ defined (which is the default). This does not affect complex
+ numbers.
+
+ "socket"
+ BSD "socket" interface. Socket addr functions require
+ inexacts or bignums for 32-bit precision.
+
+ "tick-interrupts"
+ Use if you want the ticks and ticks-interrupt functions.
+
+ "turtlegr"
+ "Turtle" graphics calls for both Borland-C and X11 from
+ sjm@ee.tut.fi.
+
+ "unix"
+ Those unix features which have not made it into the Posix
+ specs: nice, acct, lstat, readlink, symlink, mknod and sync.
+
+ "wb"
+ WB database with relational wrapper.
+
+ "wb-no-threads"
+ no-comment
+
+ "windows"
+ Microsoft Windows executable.
+
+ "x"
+ Alias for Xlib feature.
+
+ "xlib"
+ Interface to Xlib graphics routines.
+
+
+
+
+File: scm-5f2.info, Node: Saving Executable Images, Next: Installation, Prev: Building SCM, Up: Installing SCM
+
+2.4 Saving Executable Images
+============================
+
+In SCM, the ability to save running program images is called "dump"
+(*note Dump::). In order to make `dump' available to SCM, build with
+feature `dump'. `dump'ed executables are compatible with dynamic
+linking.
+
+Most of the code for "dump" is taken from `emacs-19.34/src/unex*.c'.
+No modifications to the emacs source code were required to use
+`unexelf.c'. Dump has not been ported to all platforms. If `unexec.c'
+or `unexelf.c' don't work for you, try using the appropriate `unex*.c'
+file from emacs.
+
+The `dscm4' and `dscm5' targets in the SCM `Makefile' save images from
+`udscm4' and `udscm5' executables respectively.
+
+"Address space layout randomization" interferes with `dump'. Here are
+the fixes for various operating-systems:
+
+Fedora-Core-1
+ Remove the `#' from the line `#SETARCH = setarch i386' in the
+ `Makefile'.
+
+Fedora-Core-3
+ `http://jamesthornton.com/writing/emacs-compile.html' [For FC3]
+ combreloc has become the default for recent GNU ld, which breaks
+ the unexec/undump on all versions of both Emacs and XEmacs...
+
+ Override by adding the following to `udscm5.opt':
+ `--linker-options="-z nocombreloc"'
+
+Linux Kernels later than 2.6.11
+`http://www.opensubscriber.com/message/emacs-devel@gnu.org/1007118.html'
+ mentions the "exec-shield" feature. Kernels later than 2.6.11
+ must do (as root):
+
+ echo 0 > /proc/sys/kernel/randomize_va_space
+
+ before dumping. `Makefile' has this `randomize_va_space' stuffing
+ scripted for targets `dscm4' and `dscm5'. You must either set
+ `randomize_va_space' to 0 or run as root to dump.
+
+OS-X 10.6
+`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.
+
+
+
+
+File: scm-5f2.info, Node: Installation, Next: Troubleshooting and Testing, Prev: Saving Executable Images, Up: Installing SCM
+
+2.5 Installation
+================
+
+Once `scmlit', `scm', and `dlls' have been built, these commands will
+install them to the locations specified when you ran `./configure':
+
+ bash$ (cd scm; make install)
+ bash$ (cd slib; make install)
+
+Note that installation to system directories (like `/usr/bin/') will
+require that those commands be run as root:
+
+ bash$ (cd scm; sudo make install)
+ bash$ (cd slib; sudo make install)
+
+
+
+File: scm-5f2.info, Node: Problems Compiling, Next: Problems Linking, Prev: Troubleshooting and Testing, Up: Troubleshooting and Testing
+
+2.6.1 Problems Compiling
+------------------------
FILE PROBLEM / MESSAGE HOW TO FIX
*.c include file not found. Correct the status of
@@ -256,22 +941,25 @@ scl.c syntax error. #define SYSTNAME to your system
-File: scm.info, Node: Problems Linking, Next: Problems Running, Prev: Problems Compiling, Up: Installing SCM
+File: scm-5f2.info, Node: Problems Linking, Next: Testing, Prev: Problems Compiling, Up: Troubleshooting and Testing
-2.9 Problems Linking
-====================
+2.6.2 Problems Linking
+----------------------
PROBLEM HOW TO FIX
_sin etc. missing. Uncomment LIBS in makefile.
-File: scm.info, Node: Problems Running, Next: Testing, Prev: Problems Linking, Up: Installing SCM
+File: scm-5f2.info, Node: Problems Starting, Next: Problems Running, Prev: Testing, Up: Troubleshooting and Testing
-2.10 Problems Running
-=====================
+2.6.4 Problems Starting
+-----------------------
PROBLEM HOW TO FIX
+/bin/bash: scm: program not found Is `scm' in a `$PATH' directory?
+/bin/bash: /usr/local/bin/scm: `chmod +x /usr/local/bin/scm'
+Permission denied
Opening message and then machine Change memory model option to C
crashes. compiler (or makefile).
Make sure sizet definition is
@@ -288,17 +976,17 @@ remove <FLAG> in scmfig.h and Do so and recompile files.
recompile scm.
add <FLAG> in scmfig.h and
recompile scm.
-ERROR: Init5e5.scm not found. Assign correct IMPLINIT in makefile
+ERROR: Init5f1.scm not found. Assign correct IMPLINIT in makefile
or scmfig.h.
Define environment variable
SCM_INIT_PATH to be the full
- pathname of Init5e5.scm.
+ pathname of Init5f1.scm.
WARNING: require.scm not found. Define environment variable
SCHEME_LIBRARY_PATH to be the full
pathname of the scheme library
[SLIB].
Change library-vicinity in
- Init5e5.scm to point to library or
+ Init5f1.scm to point to library or
remove.
Make sure the value of
(library-vicinity) has a trailing
@@ -306,44 +994,10 @@ WARNING: require.scm not found. Define environment variable
-File: scm.info, Node: Testing, Next: Reporting Problems, Prev: Problems Running, Up: Installing SCM
-
-2.11 Testing
-============
-
-Loading `r4rstest.scm' in the distribution will run an [R4RS]
-conformance test on `scm'.
-
- > (load "r4rstest.scm")
- -|
- ;loading "r4rstest.scm"
- SECTION(2 1)
- SECTION(3 4)
- #<primitive-procedure boolean?>
- #<primitive-procedure char?>
- #<primitive-procedure null?>
- #<primitive-procedure number?>
- ...
-
-Loading `pi.scm' in the distribution will enable you to compute digits
-of pi.
-
- > (load "pi")
- ;loading "pi"
- ;done loading "pi.scm"
- ;Evaluation took 20 ms (0 in gc) 767 cells work, 233.B other
- #<unspecified>
- > (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
- #<unspecified>
+File: scm-5f2.info, Node: Problems Running, Next: Reporting Problems, Prev: Problems Starting, Up: Troubleshooting and Testing
-Loading `bench.scm' will compute and display performance statistics of
-SCM running `pi.scm'. `make bench' or `make benchlit' appends the
-performance report to the file `BenchLog', facilitating tracking
-effects of changes to SCM on performance.
+2.6.5 Problems Running
+----------------------
PROBLEM HOW TO FIX
Runs some and then machine crashes. See above under machine crashes.
@@ -359,7 +1013,7 @@ Some symbol names print incorrectly. Change memory model option to C
than HEAP_SEG_SIZE).
ERROR: Rogue pointer in Heap. See above under machine crashes.
Newlines don't appear correctly in Check file mode (define OPEN_... in
-output files. `Init5e5.scm').
+output files. `Init5f1.scm').
Spaces or control characters appear Check character defines in
in symbol names. `scmfig.h'.
Negative numbers turn positive. Check SRS in `scmfig.h'.
@@ -369,13 +1023,79 @@ VMS: Couldn't unwind stack. #define CHEAP_CONTINUATIONS in
`scmfig.h'.
VAX: botched longjmp.
-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 _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 `continue.c'.
+
+
+File: scm-5f2.info, Node: Reporting Problems, Prev: Problems Running, Up: Troubleshooting and Testing
+
+2.6.6 Reporting Problems
+------------------------
+
+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 `agj@alum.mit.edu' or `scm-discuss@gnu.org'.
+The bug report should include:
+
+ 1. The version of SCM (printed when SCM is invoked with no arguments).
+
+ 2. The type of computer you are using.
+
+ 3. The name and version of your computer's operating system.
+
+ 4. The values of the environment variables `SCM_INIT_PATH' and
+ `SCHEME_LIBRARY_PATH'.
+
+ 5. The name and version of your C compiler.
+
+ 6. If you are using an executable from a distribution, the name,
+ vendor, and date of that distribution. In this case,
+ corresponding with the vendor is recommended.
+
+
+
+File: scm-5f2.info, Node: Editing Scheme Code, Next: Debugging Scheme Code, Prev: SCM Session, Up: Operational Features
+
+3.7 Editing Scheme Code
+=======================
+
+ -- Function: ed arg1 ...
+ The value of the environment variable `EDITOR' (or just `ed' if it
+ isn't defined) is invoked as a command with arguments ARG1 ....
+
+ -- Function: ed filename
+ If SCM is compiled under VMS `ed' will invoke the editor with a
+ single the single argument FILENAME.
+
+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 `M-x run-scheme' with SCM. Otherwise, use the emacs
+ command `M-x suspend-emacs'; or see "other systems" below.
+
+Epsilon (MS-DOS):
+ There is lisp (and scheme) mode available by use of the package
+ `LISP.E'. It offers several different indentation formats. With
+ this package, buffers holding files ending in `.L', `.LSP', `.S',
+ and `.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 `-e512 -m0' are neccessary to
+ manage RAM properly. It has been reported that when compiling SCM
+ with Turbo C, you need to `#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.
+
+other systems:
+ Define the environment variable `EDITOR' to be the name of the
+ editing program you use. The SCM procedure `(ed arg1 ...)' will
+ invoke your editor and return to SCM when you exit the editor. The
+ following definition is convenient:
+
+ (define (e) (ed "work.scm") (load "work.scm"))
+
+ Typing `(e)' will invoke the editor with the file of interest.
+ After editing, the modified file will be loaded.