diff options
Diffstat (limited to 'README')
| -rwxr-xr-x[-rw-r--r--] | README | 996 |
1 files changed, 858 insertions, 138 deletions
@@ -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. |