$Id: INSTALL,v 1.78 2022-03-25 20:11:58 phil Exp $

       ``The Macro Implementation of SNOBOL4 in C'' (CSNOBOL4)
		      Installation instructions

Un*x/POSIX/Linux systems (including Cygwin)
===========================================

Compilation
-----------

The "m4" macro processor is required.  In most cases all you need to
type is "make". NOTE: parallel make (-j option) will fail.

CSNOBOL 2.2 has been tested on Linux, FreeBSD, MacOS, NetBSD, OpenBSD
and OpenIndiana.

Some extensions will only be built if necessary support is found
(in some Linux distributions this requires both library and
"development" packages to be installed):

* ffi depends on libffi.
* sqlite depends on libsqlite3 (or "amalgamation" source in module/sqlite3).
* tcl depends on libtcl
* ndbm will fall back to a provided "sdbm" library if no system version
	of Berkeley DB or GNU DBM can be found. GDBM support may require
	"compat" package(s) as well.

The top level makefile will run the "configure" script to create
config.m4, config.sno 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
		Used for snobol4, modules and DLL.
		To specify libraries for snobol4 executable, see -add-snobol4-ldflags

	--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-snobol4-ldflags=STRING
		Add additional flags to final load command for snobol4 binary
		(eg; -llibrary)

	--add-srcs=STRING
		Add additional source files for "make depend"

	--add-warn=STRING
		Add additional C Compiler warning options.
	--debug
		Debug the configure script.

	--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,
		AND HAS NOT BEEN TRIED RECENTLY.

		It will probably fail the regression test diag1 when
		it tries to use IDENT() to compare two REAL values.

		Try using --longlong instead!

	--fast
		This option should be considered experimental, and
		unlikely to give useful results!!

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

		If the build fails, try not using it!!

		There is a Perl CPUFlags script:

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

		that might suggest 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 a
		provided 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 (or appear to be) available.

	--longlong
		Use the 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 HAS NOT BEEN RECENTLY TESTED.

	--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 allows larger strings (4GB vs. 16MB) and
		compound objects (128M descriptors vs.  2M).

		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.

	--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
		preference 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

	--bindir=DIR
		Supply a directory binary files. Default is PREFIX/bin

	--snolibdir=DIR
		Supply a directory for library files. Default is PREFIX/lib

	--mandir=DIR
		Supply a directory for man pages. Default is PREFIX/man

	--with-tcl=/path/to/tclConfig.sh
		Compile in Tcl extension (see snobol4tcl man page)
		Tk 8.4 or later is necessary to use Tcl/Tk.

	--without-blocks
		Do not include BLOCKS extension.
		Requires working install of snobol4 to rebuild
		sources.

	--without-com
		Do not compile in COM extension on CygWIN.

	--with-docs
		Install HTML versions of manual pages.

	--without-docs
		Do not install HTML versions of manual pages.

	--without-readline
		Do not compile in READLINE.

	--without-modules
		Do not compile any extension modules.

	--without-ndbm
		Do not try to compile NDBM extension module.
		See --force-sdbm

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@regressive.org).

I've spent MANY 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 making a gift.

This release was encouraged on by a gift from a long time user
who has used CSNOBOL4 in their work.

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

On systems where locally installed includes and libraries are in
locations not automatically searched by the C compiler, for example on
MacOS using MacPorts, run configure with --add-cppflags=-I/opt/local/include
and --add-ldflags=-I/opt/local/lib

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 less well tested.

Windows
-------

The Windows port has been tested with Visual Studio 2019
(free Community Edition) on 64-bit Windows 10.

These instructions are for building on Windows.
If you're installing binaries, see pkg/win32/README.win32

In the VS installer, there should be a "Workloads" tab.  The only tool
set needed is "Desktop development with C++".

Once it's installed click on the Windows menu, scroll down to "Visual
Studio 2019" and select "x64 Native Tools Command Prompt" and you
should be in a CMD window with the proper environment variables set.

Use the cd command to navigate to where you downloaded the snobol-2.1.x.tar.gz
file to, ie:

    cd C:\Users\Myname\Downloads

Extract the tar file (where x.y.z is the current version):
    tar -x -z -f snobol-x.y.z.tar.gz

and type (where x.y.z is the current version):
    cd snobol-x.y.z
    make.bat

and then
    pkg\win32\install.bat

NOTE: Not all DLL loadable code has been tested.

To compile a native Windows binary using MINGW (http://www.mingw.org):
	make -f config/win32/mingw.mak

To compile using Borland C
(not tested in a long time, almost certainly broken):
	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 Meißner 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.

VMS
---

VMS support has has not been tested in a long time. 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

Some update will be required to get it to build!
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.

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
Anonymized results are published at http://www.regressive.org/snobol4/csnobol4/
And you will be notified when test versions are available.

Announcements of new releases are made on the SNOBOL4 mailing list.
See http://tech.groups.yahoo.com/group/snobol/
