$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/