$Id: INSTALL,v 1.55 2005/12/12 17:48:22 phil Exp $ ``The Macro Implementation of SNOBOL4 in C'' (CSNOBOL4) Installation instructions Unix systems (or systems with POSIX shell, make, awk and m4); ============================================================ Compilation ----------- In most cases all you need to type is "make". The top level makefile will run the "configure" script to create config.m4 and config.h. config.m4 is used to create Makefile2, which is then run, creating a test version of snobol4 (named "xsnobol4") which is then regression tested and timed, and finally named "snobol4". The "configure" script tries to use the available C compiler which works best. If you wish to alter configure's decision process, you can run it manually by typing "./configure OPTIONS" with zero or more of the following options (multiple instances of options that begin with "--add-" can appear); --add-cppflags=STRING Add additional C preprocessor flags to compile command lines (see also --add-define) --add-define=NAME=VALUE Add additional C preprocessor '#define NAME VALUE' to config.h (available to separately compiled loadable modules) --add-ldflags=STRING Add additional flags to final load command (ie; -lxxx) --add-objs=STRING Add additional object file to final load command (ie; for "poor mans load" functions) --add-opt=STRING Add additional optimization flags to compile commands. When using GCC, "--add-opt=-g" can be used to compile for debugging without disabling optimization. GCC configuration dependent options (-mXXX) are candidates for use with --add-opt= It's best to investigate whether additional options actually improve performance (by examining before and after versions of timing.out)!! --add-srcs=STRING Add additional source files for "make depend" --add-warn=STRING Add additional C Compiler warning options. --double Use C "double" data type to represent SNOBOL4 REALs. This is the default when the environment defaults to 64-bit integers, or --lp64 or --longlong has been specified. The additional overhead of moving larger descriptors around will negatively impact performance, even when floating point is not being used. Does not effect size of INTEGER data type (see --longlong), or the maximum object size (see --no-bitfields). NOTE! THIS IS UNLIKELY TO WORK! It will probably fail the regression test diag1 when it tries to use IDENT() to compare two REAL values. Try using --longlong instead! --fast Enable use of vendor C compiler options which may make snobol4 run faster, but may make the executable less portable (e.g. by using instructions not available on all systems). This option should be considered experimental. If the build fails, try not using it!! --force-gcc Force use of GCC, the GNU C Compiler; fail if GCC not available. --force-memmove Force use of system memmove() function (if present) if no bcopy() function is available. Otherwise the bcopy.c source file will be used. --force-sdbm Force use of SDBM, a free portable DBM replacement included in the CSNOBOL4 distribution, even when alternatives are available. --longlong Attempt to use C "long long" data type to represent SNOBOL4 INTEGERs when the default data model uses 32-bit integers, longs and pointers (ILP32). Requires "long long" support in the chosen C compiler, and will use C99 numeric conversion routines if they are available, missing functions are supplied if the C runtime lacks them. This option does not alter the C type used to represent REAL data (see --double), or the maximum object size (see --no-bitfields). *** NOTE *** Use of this option will not increase the address space available to SNOBOL4, but will incur increased storage and processing overhead (see --lp64 for more information). On systems which support the LP64 (64-bit longs and pointers) data model as an option, using --lp64 is a better idea. *** WARNING *** Expect to see large numbers of C compiler warnings when using this option with GCC. This option is experimental, and has not been extensively tested, particularly with vendor supplied C compilers. --lp64 Force the use of defines for LP64 (64-bit long and pointer) data model where available, but not the default. This option attempts to set native compiler options for LP64 environment where it's not the default. If you know the right option(s) for your platform you can use --add-opt to turn them on. Under the LP64 model, SNOBOL4 INTEGERs are represented by C longs and REALs are represented C doubles. The LP64 model doubles the size of each SIL descriptor, and while it allows larger strings (4GB vs. 16MB) and compound objects (128M descriptors vs. 2M), the increased descriptor and arithmetic type sizes also degrade performance. If the underlying C compiler does not implement the LP64 model, this option may have disastrous results. It does NOT select use of "long long" to represent SNOBOL4 integers, so --lp64 is useless on 32-bit systems (see --longlong). --lp64 is not necessary on systems where LP64 is the default, or only data model (e.g. Alpha). Note that under HP-UX on IA-64 (Itanium) the default data model is ILP32, while under Linux, the default is LP64. --no-dlopen Disable use of Unix98 dlopen() API for dynamic LOAD() support --no-bitfields Disable use of C bitfields for SIL (SNOBOL Implementation Language) descriptors (basic unit of storage). This defaults to "on" when --lp64 is enabled (or the default). With 32-bit INTEGERs, the usable descriptor size field will increase from 24 bits to 31 bits, increasing the maximum string size from 16MB to 2GB, the largest array from 2M entries to over 171M entries, and the largest table from 1M entries to over 85M entries. With 64-bit INTEGERs (--longlong), the usable descriptor size field will increase from 24 bits to 32 bits, increasing the maximum string size from 16MB to 4GB, the largest array from 2M entries to over 256M entries, and the largest table from 1M entries to over 128M entries. In most cases the larger descriptor size will decrease performance. Despite not having to deal with packing and unpacking a 24-bit field, the larger descriptor means increased memory bandwidth use, and less efficient use of the CPU data cache. --no-dynlib Disable use of all dynamic LOAD() support mechanisms --no-gcc Don't look for GNU C Compiler (gcc). However, if the cc command is GCC based, it will be used. --no-inline Disable any compiler options for code inlining, select snobol4.c (which has not been reordered to facilitate inlining) instead of isnobol4.c --no-largefile Disable automatic selection of large file (>2GB) support. If autoconf manages to turn on 64-bit file set type (off_t) but fseeko function prototype is missing, the "update.sno" regression test will fail. Using this option will allow you to build snobol4 without attempting to use large file support. --no-opt Turn off C compiler optimization. --opt=STRING Supply C optimization flags. The default value when using GCC is "-O3" (the -finline-functions flag is supplied separately except when --no-inline has been given). If the C compiler being used is not GCC based, the default "-O", which is widely accepted. Other values to try depend on the C compiler in use. Different values to try; SunPro/Sun Workshop: -fast If you can tell me good values to use, and how to detect the compiler to use them on, please let me know! Optimized compilation mail fail, to compile the large machine generated files (due to swap space exhaustion, or internal compiler limits), or may appear to take forever to compile. --opt=-g can be used to compile for debugging, with no optimization. When using GCC --add-opt=-g can be used to compile for debugging without disabling optimization. To turn off optimization, see --no-opt --prefix=DIR Supply a directory prefix for bin/ and lib/ directories. Default prefix is /usr/local --with-tcl Try to compile in Tcl extension (see snobol4dbm man page) A shared library installation of Tcl version 8.4 or later is HIGHLY desirable! See --with-tk --with-tk If --with-tcl has been given, and the most recent version of Tcl available is prior to version 8.4, if you want to use the Tk GUI toolkit, it will need to be linked in. If Tcl and Tk are staticly linked, this may expand the snobol4 executable file four times (from around 333K to around 1333K)!! Consider installing newer, shared library versions of Tcl and Tk!!! --without-ndbm Do not try to compile in NDBM extension (see snobol4dbm man page) The configure script tries to select from among different versions of system support functions, including "dummy" versions which allow the software to be built, with reduced functionality. If this occurs, or if the build does not succeed, you can consult doc/porting.txt (also available as html) for information on the available options for use in creating a system-specific config file. If you need assistance please contact me (phil@ultimate.com). I've spent untold hours working on this release (time, which if I had billed a client would have been in the tens of thousands of dollars), if you find it useful, please consider sending me a gift! This release was spurred on by a small donation (a user who gives each year when he renews his Public Broadcasting membership). I'm also available for contract development. For information on including "external" C functions in the linked binary see doc/load.txt. Installation ------------ Typing "make install" will install the snobol4 binary and man page. The snobol4 (PREFIX/bin/snobol4), library directory (PREFIX/lib/snobol4) and man page (PREFIX/man/man1/snobol4.1). The default PREFIX is /usr/local, see --prefix= configure option above). Please mail timing.out files to snobol4-timing@regressive.org!!! For more information on configuration, see the next section: "Advanced configuration". For information on porting this software to a new system see doc/porting.txt. Advanced configuration on Unix ============================== Most Unix users won't need to read any further than this! There are several ways to alter the configuration without resorting to editing Makefile2 (which can be overwritten at any time). One reason to alter your configuration would be because the automatically generated configuration would not build (please let me know if this happens)! Another would be to customize your system (for example, adding new built-in functions, especially via the "Poor Mans LOAD()" facility (see doc/load.txt)). local-config ------------ If the file "local-config" exists, the autoconf script will append it's contents to config.m4 (used to generate Makefile2). Makefile variables that can be overridden; OPT Optimization flags (set by --opt=); "OPT=-g" will turn optimization off and enable debug symbols. SNOBOL4_C_CFLAGS C compiler flags that will be used for (i)snobol4.c in ADDITION to the usual CFLAGS. (i)snobol4.c is the translated SIL code, and is large and complicated. In the past some C compilers have needed additional options set (e.g. to raise internal limits) in order to compile (i)snobol4.c DATA_INIT_CFLAGS DATA_INIT_CFLAGS controls the C compiler flags used to compile data_init.c data_init.c contains (via data_init.h) the data initializers from the SIL code. The code is run once, and while optimization can save space (by detecting use of the same constant in different places), it can take a while to compile. When doing development on a slower machine this is no fun, and I use "DATA_INIT_CFLAGS=" to turn off optimization. If additional compiler flags are needed in order to compile data_init.c, you could use "DATA_INIT_CFLAGS=$(CFLAGS) stuff" The following are m4 macros defined in Makefile2.m4 before the inclusion of config.m4. The m4 begin and end quote characters are set to '[' and ']', and it's advisable to quote all arguments passed to the macros (lest you type a word that's the name on an m4 macro); ADD_OPT() Add C compiler optimization options ADD_CPPFLAGS() Add C preprocessor options (e.g. -D -U -I) to CFLAGS. NOTE! For most things, it's probably better to use local-defines (see below). ADD_SRCS() Add source files to be included in the "make depend" process ADD_OBJS() Add object files to be linked into the snobol4 executable. ADD_LDFLAGS() Add loader (ld) options. Can be used to control libraries (e.g. -l -L) local-config ------------ If the file "local-config" exists, the autoconf script will append it's contents to config.h. config.h will be installed in a public location for inclusion into user loadable modules, so #defines that are necessary, or useful for their compilation should be placed in the local-config file. Non-unix systems; ================ The non-unix ports are not well tested. Please send me any fixes you discover! See doc/porting.txt for details on porting CSNOBOL4. The routines in tty.c (tty_save, tty_restore, tty_mode, tty_close) and inet.c (tcp_open, udp_open) need to be supplied. Dummy versions exist in lib/dummy/tty.c and lib/dummy/inet.c. The functions referenced from pml.h will not be loaded by the existing command files, and will cause the link to fail. There are three possible solutions; 1. Add commands to build a SNOLIB library and include it in the link. 2. Compile the needed objects and add them directly to the link command. 3. Define one or more of NO_PML_(HOST|EXIT|REAL|FILE|DELETE|RENAME) when compiling pml.c. The SPITBOL HOST() function simulation may call functions not available on the target system. Rather than adding a nest of ifdefs, dummy versions of getenv() and system() have been provided in the lib/dummy directory for this eventuality. The SPITBOL EXIT() simulation requires an execute() function to pass pass control to another program. A dummy version is provided in lib/dummy/execute.c. VMS using DEC C --------------- CSNOBOL4 has been run on VMS (VAX, Alpha, and IA64), config/vms/descrip.mms is an MMS description file, which can be used by typing: MMS /DESCRIP=[.CONFIG.VMS]DESCRIP.MMS If using VAXC, /MACRO=(VAX_C=1) should be appended to the command line. If using an older version of Alpha DECC, try adding /MACRO=(DECC4=1) The VMS port tries to use native calls to implement TTY I/O, and supports binary and noecho input. TCP/IP I/O is implemented using TCP/IP Connection services for OpenVMS (formerly VAX/Ultrix connection product). It should be possible to use other TCP packages, but if not, or none is available, add /MACRO=(NO_TCP=1) to the MMS command line. Win32 using CygWin ------------------ Cygwin (http://cygwin.com), is a free Unix emulation environment for Windows. Normal distributions build and run correctly, with the full Unix feature set including TCP client and server functionality; just type "make"! Win32 ----- The Win32 port is in it's infancy, and has only been tested using the free MINGW C compiler. * binary and no echo support for console I/O has been added recently * TCP and UDP I/O work (with some hoop jumping) * LOAD() of external functions from DLL's implemented, but not tested To compile using MINGW (http://www.mingw.org); make -f config/win32/mingw.mak To compile using Microsoft Visual C++ (tested with Visual Studio .NET 2003); nmake -f config\win32\ntmsvc.mak To compile using Borland C (not tested); nmake -f config\win32\borland.mak DJGPP under DOS --------------- DJGPP (http://www.delorie.com/djgpp/) is a free 32-bit C/C++ MS-DOS development system, for Intel 80386 (and higher) PCs running DOS based on GCC. Burkhard Meissner has ported CSNOBOL4 to DJGPP. To compile using GNU make; make -f config/djgpp/Makefile To enable optional support for TCP/IP using WATTCP and DXE2 based external function loading, see the commented out lines in the Makefile. Anything else ------------- CSNOBOL4 has been designed to be modular, and makes only modest demands on the C library. See doc/porting.txt for information. Let me know! ============ Please let me know of your success and failures to bring up CSNOBOL4! Please mail timing.out files to snobol4-timing@regressive.org along with information on your system make, model and CPU clock, if known. Announcements of new releases are made on the SNOBOL4 mailing list. See http://www.snobol4.com/listserv.htm for information on how to join.