bwBASIC/INSTALL

Some Notes on Installation of the Bywater BASIC Interpreter:
-----------------------------------------------------------

0. Quick-Start Guide For Compiling

   To use the default configuration (which is reasonable for most situations):

   On Unix, type "configure; make".
   On MS-DOS using QuickC, type "nmake -f makefile.qcl".

   You can skip the rest of this file unless you want to customize the
   BASIC dialect that is supported, or something goes wrong in the
   above commands.

1. Compiler Requirements

   Although earlier versions of bwBASIC would compile only with
   ANSI C compilers, versions 2.10 and higher can be compiled
   with "stock" C compilers, i.e., compilers that comply with
   the older Kernighan and Ritchie C standard.

   Section I-B of bwbasic.h allows you to specify some compiler
   features.  If you have an ANSI C compiler, you needn't worry
   with this.  For stock C compilers, the default configuration
   presumes that your compiler supports signal() and raise()
   with the signal.h header, supports setjmp() and longjmp()
   with the setjmp.h header, and has a separate string.h
   header.  If your compiler does not have these features
   and the related header files, you can indicate this in
   section I-B by setting appropriate flags to FALSE.

   
2. Configuration of header files

   You may need to examine file "bwbasic.h" to make important
   changes for specific hardware and compiler configurations.
   You may also need to change "bwx_tty.h" if you are using the
   TTY implementation or "bwx_iqc.h" if you are using the version
   for PCs with Microsoft QuickC (see below on "implementations").
   If you want to redefine messages or even the BASIC command
   names, you will need to edit "bwb_mes.h".


3. Makefiles

   Several makefiles are provided: "makefile.qcl" will compile
   the program utilizing the Microsoft QuickC (tm) line-oriented
   compiler on DOS-based p.c.'s, and "makefile" will compile the
   program on Unix-based computers utilizing either a stock C 
   compiler or Gnu C++. I have also compiled the program utilizing 
   Borland's Turbo C++ (tm) on DOS-based machines, although I have 
   not supplied a makefile for Turbo C++.

   If you try the "IQC" implementation, you will need to alter
   makefile.qcl to include bwx_iqc.c (and bqx_iqc.obj) instead
   of bwx_tty.*.

   
4. Implementations

   The present status of bwBASIC allows two major implementations
   controlled by the IMP_TTY and IMP_IQC flags in bwbasic.h.
   IMP_TTY is the base implementation and presumes a simple
   TTY-style environment, with all keyboard and screen input
   and output directed through stdin and stdout. If IMP_TTY is
   defined as TRUE, then the file bwx_tty.h will be included,
   and a makefile should include compilation of bwx_tty.c.
   IMP_IQC is a somewhat more elaborate implementation for
   the IBM PC and compatible microcomputers utilizing the
   Microsoft QuickC compiler.  This allows some more elaborate
   commands (CLS and LOCATE) and the INKEY$ function, and
   allows greater control over output.  If IMP_IQC is defined
   as TRUE in bwbasic.h, then bwx_iqc.h will be included and
   bwx_iqc.c should be compiled in the makefile.

   Only one of the flags IMP_TTY or IMP_IQC should be set
   to TRUE.

   
5. Flags Controlling Groups of Commands and Functions 

   There are a number of flags which control groups of commands
   and functions to be implemented.  

   (core)		Commands and Functions in any implementation of
   			bwBASIC; these are the ANSI Minimal BASIC core

   INTERACTIVE		Commands supporting the interactive programming
   			environment

   COMMON_CMDS		Commands beyond ANSI Minimal BASIC which are common
   			to Full ANSI BASIC and Microsoft BASICs

   COMMON_FUNCS		Functions beyond the ANSI Mimimal BASIC core, but
   			common to both ANSI Full BASIC and Microsoft-style
   			BASIC varieties

   UNIX_CMDS		Commands which require Unix-style directory and
   			environment routines not specified in ANSI C

   STRUCT_CMDS		Commands related to structured programming; all
   			of these are part of the Full ANSI BASIC standard

   ANSI_FUNCS		Functions unique to ANSI Full BASIC

   MS_CMDS		Commands unique to Microsoft BASICs

   MS_FUNCS		Functions unique to Microsoft BASICs


6. Configurations

   The file bwbasic.h includes a number of configuration options
   that will automatically select groups of commands and functions
   according to predetermined patterns.  These are:

   CFG_ANSIMINIMAL	Conforms to ANSI Minimal BASIC standard X3.60-1978.

   CFG_COMMON      	Small implementation with commands and functions
                        common to GWBASIC (tm) and ANSI full BASIC.

   CFG_MSTYPE      	Configuration similar to Microsoft line-oriented
                        BASICs.

   CFG_ANSIFULL		Conforms to ANSI Full BASIC standard X3.113-1987
                        (subset at present).

   CFG_CUSTOM		Custom Configuration specified by user.

   Only one of these flags should be set to TRUE.


7. Adding Commands and Functions

   In order to add a new command to bwBASIC, follow the following
   procedure:

      (a) Write the command body using function bwb_null() in bwb_cmd.c
      as a template.  The command-body function (in C) must receive a
      pointer to a bwb_line structure, and must pass on a pointer to
      a bwb_line structure.  The preferred method for returning from
      a command-body function is: return bwb_zline( l ); this will
      discriminate between MULTISEG_LINES programs which advance to
      the next segment and those which advance to the next line.

      (b) Add prototypes for the command-body function in bwbasic.h;
      you'll need one prototype with arguments in the ANSI_C section
      and one prototype without arguments in the non-ANSI_C section.

      (c) Add the command to the command table in bwb_tbl.c in the
      group you have selected for it.

      (d) Increment the number of commands for the group in which
      you have placed your command.  

   The procedure for adding a new function is parallel to this, except that
   you should use fnc_null() in bwb_fnc.c as the template, and the
   function name must be added to the function table in bwb_tbl.c.