$Id: INSTALL,v 1.59 2008/09/28 21:21:51 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-cflags=STRING
		Add additional C compiler flags to all compile command lines.

		When using GCC, "--add-opt=-g" can be used to compile
		for debugging without disabling optimization.

	--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 MOST compile commands.

		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)!!

		See discussion of the CPUFlags utility under --fast
		below for how to get different optimization flags that
		may help on your platform.
		
	--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!!

		There is a Perl CPUFlags script:

			http://www.hlnum.org/english/projects/tools/cpuflags/

		that may suggest other/better choices for optimization flags
		to use with --add-opt than --fast does.

	--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.  Use of this option
		overrides any values supplied via --add-opt options
		(but not ones added by --fast).  Use --add-opt in
		perference to --opt.  There is also discussion under
		the --fast option.

		Optimized compilation may 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.

		When using GCC --add-opt=-g can be used to compile for
		debugging without disabling optimization.  To compile
		for debugging, with no optimizations, use --opt=-g

		To turn off optimization, see --no-opt

	--prefix=DIR
		Supply a directory prefix for bin/ and lib/ directories.
		Default prefix is /usr/local

	--universal
		Mac OS X: build a universal (Power PC / Intel x86) binary.

	--with-tcl
		Try to compile in Tcl extension (see snobol4tcl 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 timing@snobol4.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 timing@snobol4.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.
