From Atari Wiki
Jump to navigation Jump to search
             Welcome to Ian's Heat-and-Serve C!
         This release is version 1.40, dated 12/10/92

      *                                                 *
      * This version has been customized by Ian Lepore, *
      * and is NOT an official release of Sozobon, Ltd. *
      * Please do NOT direct any bug reports or support *
      * questions for this release to the good folks at *
      *     Sozobon...if anything goes wrong, it's      *
      *                 Not Their Fault.                *


   1.0     Introduction 
   1.1       Quick Start - Read this at the very least! 
   1.2       Overview of Heat-and-Serve C

   2.0     Installation 
   2.1       Upgrading from a prior release 
   2.2       Notes for Floppy Disk Installation 
   2.3       The INSTALL Program 
   2.4       The GEMENV Program 
   2.5       Desktop Installation Procedure 
   2.6       CLI Installation Procedure

   3.0     In Case of Difficulties 
   3.1       Trouble with MAKE 
   3.2       Trouble with Environment Variables

   4.0     Roadmap (Directory and File List)

   5.0     Credits and disclaimers

1.0 Introduction

   Welcome to Ian's Heat-and-Serve C (HSC).  I know this document is
   pretty long, but there's a lot in here you don't need to know
   unless you have trouble; installation is not a hard process at
   all.  Please read the Quick Start notes that follow, then proceed
   from there.

1.1 Quick Start

   If you are upgrading from an earlier Heat-and-Serve release, and
   are  familiar with the general installation procedure, please
   proceed to section 2.1, "Upgrading from a prior release." 
   Nothing in the rest of this document has changed significantly
   for you.

   If this is a first-time install, I strongly recommend that you at
   least browse through the sections in chapter 2.  If you just
   aren't the document-reading type, you're in luck.  Most of the
   installation process is handled by the INSTALL program.  If
   you're using the GEM desktop, the INSTALL program does everything
   for you.  If you use a CLI, you have to set some environment
   variables by hand in your CLI.

   The INSTALL program can run both in GEM and non-GEM modes.  It
   gives you several opportunities to quit before it starts
   installing the compiler.  Just unpack everything from the
   distribution archive into the same directory, run INSTALL, follow
   its directions, reboot your system to install GEMENV and
   DESKTOP.INF, and you're up-and-running.

   I still think you should browse chapter 2 before installing,

1.2 Overview of Heat-and-Serve C

   I have dubbed this offering 'Heat-and-Serve C' to avoid further
   confusion with Sozobon C's ongoing releases.  Because it's
   derived from Sozobon C, you'll still see many references to
   Sozobon, especially in directory names and such.  Besides
   avoiding confusion, I feel that this compiler has diverged enough
   from the original to warrant a separate name.

   Unlike previous Sozobon releases, this one virtually installs
   itself, and it works right away, without the need for a lot of
   customization. In addition to the easier installation, this
   release differs from the original Sozobon C v1.0 and 1.2 releases
   in the following ways:

   -  Many bug fixes over prior releases.

   -  A new version of GemFast GEM support, with many enhancements.

   -  The compiler now speaks English instead of technish when
      reporting errors.  (LD still tends to be cryptic).

   -  A desktop-friendly MAKE utility is included, as well as other
      assists for the desktop user.

   -  The compiler pieces and MAKE utility are smarter about where
      to look for files in the absence of PATH= information.

   -  Several code generation bugs were fixed in the compiler. 
      Also, several ANSI features were added, such as concatenation
      of  adjacent string literals.

   -  The TOP optimizer is vastly improved in terms of the peephole
      optimizations it does.

   -  The compiler controller (CC) program now knows how to use a
      ramdisk to hold intermediate files, for better performance.
      (Floppy disk users especially benefit from this.)

   -  Lots of performance tweaks; in particular, intelligent I/O
      buffering has been added to the compiler pieces, and the
      assembler is 50-100% faster.

   -  All libraries and runtime supports are included in the
      distribution, including the GemFast libraries for GEM
      programming, and a variety of runtime startup files for
      different environments.

   -  This release does NOT include source code (except for the
      runtime startup files and example programs.)

2.0 Installation

   HSC is supplied as a single archive file which contains
   everything needed to set up the compiler and begin writing
   programs immediately.  There is no need for you to obtain other
   support files from your network or BBS.  

   When unpacking the distribution archive (the one that contained
   this file), it is important that all the files that came out of
   it remain together in the same folder.  If any of the files are
   missing, the installation program may not be able to perform all
   the installation steps (it will whine at you).  When the
   distribution archive is unpacked, the following files emerge:

      INSTALL.DOC     - This document.
      INSTALL.PRG     - The installation utility.
      GEMENV.PRG      - Environment variable manager.
      HSBIN140.PDF    - The compiler itself, in packed format.
      HSDOC140.PDF    - The full documentation, in packed format.
      HSXMP140.PDF    - The example source code, in packed format. 

   After reviewing the installation notes below, all you need to do
   is run INSTALL.PRG, which installs and configures the compiler. 
   The installation program uses a GEM interface when it detects
   that GEM is active on your system.  (If you normally boot your
   machine straight into a CLI without allowing GEM to initialize,
   the INSTALL program detects that and runs in a text-only mode.) 
   The compiler itself does not require GEM or desktop usage once
   it's installed.

   The install program will prompt you for which installation steps
   you wish to run, and which drives or hard disk partitions you
   wish to install the parts of the compiler on.  There are three
   separate Packed Data Files, to accommodate floppy disk users.  It
   is assumed that hard disk users will generally unpack all three
   data files to the same partition, so the INSTALL program will
   pre-set its buttons for that situation.  This is optional,
   however.  The files unpacked from the HSBINxxx.PDF file MUST
   ALWAYS remain together on the same drive, but the documentation
   and examples can go anywhere.

   The packed data files will require disk space to unpack as

      HSBIN140.PDF  =   580 KBytes     
      HSDOC140.PDF  =   512 KBytes
      HSXMP140.PDF  =   138 KBytes
      Total         =  1230 KBytes Unpacked

   Note that when names of the form "x:\PATH" appear in the notes
   below the 'x' should be filled in with the drive onto which you
   unpacked the compiler (the HSBINxxx.PDF file).

2.1 Upgrading from a prior release

   If you're doing a first-time install, you can skip this section.

   The process for upgrading is identical to that of initially 
   installing, except that the GEMENV and DESKTOP.INF parts of the 
   installation can be skipped.  This version of HSC requires about
   400k more disk space than prior releases.  The increases are
   primarily in the new GemFast documentation, and the example code.

   When running INSTALL to upgrade to a newer version, every file in
   the standard distribution will be overwritten without prompting. 
   If you have modified any of your header or library files, they
   will  be replaced.  If you have added new files to the \sozobon
   directory tree, they will remain untouched.

   Either before or after running INSTALL.PRG to do the upgrade, you
   may delete the following obsolete files from \SOZOBON\DOC:


   They have been superceded by two new files with different names.

   If you are a GEM programmer, you MUST read GEMFINST.DOC and
   GEMFAST.DOC before trying to use HSC v1.40.  Changes in GemFast
   make it crucial for you to recompile your existing code before
   trying to link it with GemFast v1.8 libraries.

2.2 Notes for Floppy Disk Installation

   If you are installing to a hard disk, you can skip this section.

   The floppy disk installation procedure has been completely
   revamped for the 1.33 (and later) versions.  You no longer need
   two floppy drives or a huge ramdisk to perform the installation. 
   The process now works with a single double-sided drive, as long
   as you have at least as much free RAM in your system as the
   largest PDF installation file.  As the installation proceeds, you
   will be prompted to insert the input and output disks as needed. 
   I've tried to keep disk swaps to a minimum.

   Before starting the installation, unpack all the distribution
   files to a floppy disk.  (The PDF files, and the INSTALL and
   GEMENV programs must all be on the same floppy disk when you
   start INSTALL.PRG.)

   Next, format two double-sided floppy disks.  One disk will hold
   the compiler itself, and the other will hold the documentation
   and example files.  On the compiler disk, create an AUTO folder,
   and copy your favorite auto programs into it.  Also, put a copy
   of your usual DESKTOP.INF file onto the compiler disk.  The other
   disk does not need an AUTO folder or DESKTOP.INF.
   After preparing your floppy disks, Follow either the Desktop or
   CLI procedure below, depending on the way you intend to use HSC.

2.3 The INSTALL Program

   This section describes exactly what INSTALL.PRG does to your

   As of v1.33, the INSTALL program does not require GEM to
   function.  If you normally boot your machine into a CLI before
   GEM is initialized, INSTALL will detect this and run in a text-
   based mode instead of using GEM dialogs to interact with you. 
   The basic operation of the program in non-GEM mode is the same,
   except that the GEMENV and DESKTOP.INF updates are not done.  The
   following discussion assumes GEM mode; in CLI mode you will be
   prompted to enter a drive letter in place of clicking on a
   button, and so on.  You can force the program to run in non-GEM
   mode by supplying a parameter on the command line when you run
   it.  (Any character(s) on the command line will do.)

   INSTALL initially presents a dialog box that describes the steps
   of the installation, and has a drive button next to each step.  
   You may click on the drive button for any step to change the
   target drive or set that step to be bypassed completely.  After
   setting the drive buttons appropriately, click on the PROCEED
   button to run the installation steps which were not set for
   bypass. Even after clicking on PROCEED, you will be prompted for
   one more chance to stop the installation before any data is
   unpacked or any of your system files are modified.

   The install program takes the following steps (assuming none are

   1. It installs the compiler.  This step unpacks the contents of
      HSBINxxx.PDF to the indicated drive.  The unpacking process
      will create a \SOZOBON folder in the root of the target drive,
      and will create other folders within \SOZOBON.  When this
      option is active (ie, not bypassed), you will be prompted for
      two additional parameters after clicking on PROCEED, the I/O
      buffer size, and the device for temporary files.  Both of
      these options are entered via GEM dialog boxes which contain a
      description of the parameters and recommended settings.

   2. It installs the documentation.  This step unpacks the contents
      of HSDOCxxx.PDF to the indicated drive.    

   3. It installs the example programs.  This step unpacks the
      contents of HSXMPxxx.PDF to the indicated drive.    

   4. It installs GEMENV.PRG into the AUTO folder on the indicated
      drive. The GEMENV program is described below.  If you are
      using the standard GEM desktop, or DCDesktop, you must run
      this step.  If you are using a CLI, GEMINI, NeoDesk, or other
      alternate desktops that have builtin support for environment
      variables, you may bypass this step, and manually configure
      your env variables to the values described in the CLI

   5. It modifies the DESKTOP.INF file on the indicated drive to
      install MAKE.TTP as the application to handle double-clicks on
      files ending in .MAK.  If you are using the GEM desktop or
      DCDesktop, you may run this step, or take the corresponding
      action manually.  If you are running different alternate
      desktop, you will need to follow whatever procedure exists for
      that desktop to install an application to handle double-clicks
      on .MAK files.  If you will be using HSC only from a CLI, this
      step may be bypassed.  Note that during the installation of
      GEMENV and modification of your DESKTOP.INF file, the install
      program will rename your existing ROOT.ENV or DESKTOP.INF file
      (if any) to end in .BAK, to provide you with a quick recovery
      if anything goes wrong.

   The change to DESKTOP.INF to install MAKE as the application for
   *.MAK files is described in detail in \SOZOBON\DOC\ST_MAKE.DOC.

2.4 The GEMENV Program

   The GEMENV program installed in step 4 is a TSR that gives the
   desktop the ability to handle environment variables.  It is
   described in detail in \SOZOBON\DOC\GEMENV.DOC.  It is a 'passive
   TSR'; that is, it only allocates a 1k data area in memory and
   then terminates leaving that memory resident.  It leaves no hooks
   in the operating system after the desktop is started.  The memory
   is used to store environment variables.  You may also
   double-click on GEMENV.PRG from the desktop at any time; online
   help is available in the program.

   If you decide to run without GEMENV for some reason, it will
   probably be necessary to edit the x:\SOZOBON\BIN\MAKE.INI file
   and uncomment the statements in the .INICMDS section.  In this
   case, your best bet is to install everything on your C:  drive,
   or always run the compiler only from the drive it is installed
   on. See the 'Trouble with MAKE' section, below, for more hints on
   how to run without GEMENV.  (Your best bet, by far, is to use

   When you use an alternate desktop, or other programs which run
   from AUTO but take effect after the desktop is started, it may be
   necessary to ensure GEMENV runs early in the AUTO folder
   processing.  This is not a problem with GEMENV, but rather a side
   effect of the way alternate desktop programs install themselves
   into the same system vector that GEMENV uses to borrow control
   from the system for a moment just before the desktop starts.

2.5 Desktop Installation Procedure

   To use HSC from the desktop, perform the following steps:

   1. Unpack the entire distribution archive to any disk you want,
      but unpack all the files to the same folder.

   2. Run INSTALL.PRG.  See the description in section 2.3, above. 
      For use from the GEM desktop, you should generally allow all
      the installation steps to run.    

   3. At this point, if you are using an alternate desktop, take     
      whatever manual steps are necessary to correspond to the     
      INSTALL.PRG steps that were bypassed.  (IE, configure your    
      environment variables as described in the CLI installation,    
      below, and install MAKE.TTP as the application for .MAK

   4. Reboot, to make the GEMENV program and new DESKTOP.INF file    
      install themselves in the system.

   5. Open a window on \SOZOBON\EXAMPLES and double-click on
      MAKEFILE.MAK.  This will run a series of tests on the
      compiler.  See the 'In Case of Difficulties' section, below,
      if the tests don't work.  Some of the tests create GEM
      programs, but they are not run from the makefile because GEM
      programs can't be started from a .TTP.  After they are
      compiled, just double-click on them from the desktop.  (The
      GEM programs are generated into their own folders inside the
      EXAMPLES folder.)

2.6 CLI Installation Procedure

   To use HSC from a command shell (such as Gulam), perform the
   following steps:

   1. Unpack the entire distribution archive to any disk you want,
      but unpack all the files to the same folder.    

   2. Run INSTALL.PRG.  See the description in section 2.3, above. 
      To use the compiler from a command shell, you should generally
      set the GEMENV and DESKTOP.INF installation steps to BYPASS.

   3. Using whatever method is provided by your CLI, set the    
      following environment variables:


      The TMP variable is optional.  If you have a fast device such
      as a ramdisk, you can use it for intermediate files by putting
      its drive letter in the TMP= variable.

      For the PATH variable, the path listed above may be added to
      your existing path list, separated with commas or semicolons.
      The trailing slash on the pathnames is optional -- include
      them or not based on what your other software prefers.  (Note
      that TOS 1.0 GEM *really* likes to see C:\ as the first path
      in the PATH= list!  If you use TOS 1.0, it's best to ensure
      that C:\ is always first.)  The BUFSIZE value may be set to
      anything between 1024 and 32512, in multiples of 512.  If you
      have the memory to spare, 8k or 16k works well.

   4. Enter whatever command needed to make \SOZOBON\EXAMPLES the 
      current directory, and type MAKE.  This will run a series of
      tests on the installation.  Part of the testing includes
      compiling GEM programs, but they are not run automatically
      from the makefile.

3.0 In Case of Difficulties

   Most problems with HSC come from two sources: 1) trouble in your
   makefile, and 2) the compiler can't find its support files.

3.1 Trouble with MAKE

   For makefile troubles, about the best advice I can offer is to
   read MAKE.DOC and ST_MAKE.DOC about 20 times, and rely heavily on
   the stuff in the examples directory.  Remember that the '-p' and
   '-d' MAKE options can be useful in debugging problems in your
   makefiles.  Also remember that if you are running MAKE from the
   desktop, you can hold down either SHIFT key while clicking on the
   .MAK file to get prompted for options.

   If double-clicking on a .MAK file doesn't cause MAKE.TTP to run,
   double-check your DESKTOP.INF file (see ST_MAKE.DOC for details
   on the DESKTOP.INF installation line). If MAKE.TTP starts, but
   warns that it can't find MAKE.INI, check your PATH= environment
   variable, or create a C:\SOZOBON\BIN dir and put MAKE.INI in
   there.  If make runs, but reports trouble finding the HSC
   compiler programs, check the contents of the MAKE.INI file,
   especially the pathnames in the .INICMDS area.

3.2 Trouble with Environment Variables

   When the compiler has trouble finding its support files, it
   almost always comes down to trouble with your environment
   variables. Since the GEM desktop doesn't directly support env
   vars, this used to be 99% of everyone's Sozobon troubles.  With
   the new GEMENV program, this trouble basically disappears.  Even
   without help from GEMENV, this release of HSC is pretty good at
   finding its pieces.  It will search in the \SOZOBON path of the
   current drive, and if that fails, it will look for C:\SOZOBON
   paths.  This implies that if you don't want to use GEMENV for
   some reason, you can always install the compiler on the C: drive
   and expect things to work no matter what drive your source code
   is on.

   To make debugging the path-related problems a little easier, a
   program is included in the \SOZOBON\SPECIAL directory, called
   NAMETRAK.PRG.  When you run this program, it installs itself into
   the DOS vector and logs to the printer all file-related activity.
   Often, by installing NAMETRAK and then running the HSC compiler,
   you can find out where it is looking for files and either move
   everything to there (a kind of crude solution!) or make
   adjustments in your env vars.  You must reboot your machine to
   de-install the NAMETRAK program.

   Another debugging program, SHOWENV.TOS, simply displays to the
   screen the contents of all the environment variables currently in
   effect.  Whatever you see here is what the compiler and MAKE will
   see when they are run.  This is a normal program, not a TSR.

4.0 Roadmap

   This section provides an overview of the HSC directory structure
   and points out some important files.  When the distribution
   archive is unpacked, it creates the following directory

      \SOZOBON      - The Sozobon root, no files here.
        \BIN      - The executables.
        \INCLUDE  - The C header files for #include.
        \LIB      - The runtime libs and startup files.
        \DOC      - Documentation for everything.
        \EXAMPLES - Example programs.
        \SPECIAL  - Desktop assists and troubleshooting.


   This directory contains all the executables to run HSC, including
   MAKE, and including the MAKE.INI file required to supply MAKE
   with rules appropriate to compiling HSC programs.  If you have a
   consolidated \BIN directory elsewhere in your system, and you
   feel brave, you can copy the contents of the \SOZOBON\BIN
   directory to your single \BIN directory, adjust your PATH=
   statement accordingly, and run.  (This is what I do.)  However,
   this sort of messing around with the HSC structure is not for the
   faint-hearted or easily-frustrated programmer. 


   This directory holds all the header files for HSC (except those
   you write yourself for your own applications -- those would be in
   the same directory as the application source code).  The files in
   this directory are originally from the dLibs12 distribution
   package that corresponds to HSC, and from the GemFast GEM
   programming library package.

   If you have your own system of library files and headers, or if
   you modify any of the delivered headers, it is recommended that
   you create a new folder for them.  If you do this, set the
   INCLUDE= environment variable to contain the pathname of your
   folder followed by the \SOZOBON\INCLUDE folder (separate the two
   pathnames with a semicolon).  Keeping this separation will ensure
   that you don't lose your modifications when upgrading to a new
   version of HSC or dLibs.


   This directory contains the runtime libraries that are linked
   with your program by LD in the final stage of a compile.  The
   dlibs.a file contains the bulk of the runtime support.  The
   libm.a file contains floating-point math support, and is needed
   only when you use floating point variables in your program.  The
   vdifast.a and aesfast.a files contain the GEM runtime libraries,
   they are needed only when you write GEM programs.  In addition,
   the runtime startup files that are linked ahead of your program
   are located here, including the source code.  The startup files,
   and the situations they are good for, are as follows:

     DSTART.O    -  Standard runtime startup, for use with dlibs.a. 
                    This is required if you use stream I/O (fopen,
                    fclose, printf, etc).

     APSTART.O   -  A stripped-down startup file useful for GEM
                    programming.  This startup will give you
                    command-line arguments (argc/argv), but will not
                    automatically open or close stream I/O. The
                    argc/argv support in this startup file does NOT
                    include XARGS or ARGV support!

     MINSTART.O  -  A very small startup file useful primarily for
                    desk accessories and GEM programs that don't need
                    argc/argv.  This startup can also be used to
                    create a program that runs as either a .PRG or
                    .ACC when you rename the program file.

   The notes about extended or modified files under \SOZOBON\INCLUDE
   above apply to this directory as well.  It is safer to create a
   new directory for your extensions to prevent troubles when
   upgrading. If you do this, be sure to modify the LIB= env var.


   This directory contains all the documentation in the HSC system
   including a copy of the document you are reading now.

   The documents are:

     SOZOBON.DOC    The docs originally released with Sozobon, but
                    modified a bit for this release.  This doc may
                    contain references for tools not included in this
                    release because they are rarely used.  This is
                    where you'll find references for all the
                    command-line options of the various compiler

     DLIBS.DOC      The runtime library reference. This documents all
                    the typical C functions such as fopen(),
                    strcpy(), and so on.

     GEMFAST.DOC    The GemFast library function reference and
                    programming guide.

     GEMFINST.DOC   GemFast installation and portability notes.

     MAKE.DOC       Documents for the MAKE utility.  MAKE.DOC is a
     ST_MAKE.DOC    general overview of MAKE for those unfamiliar
                    with it. ST_MAKE.DOC describes implementation and
                    ST-related features, and has the STMAKE revision
                    history notes.

     GEMENV.DOC     Docs for the GEMENV TSR program, and some        
                    discussion of environment variables in general.

     VRSN_xxxx.DOC  Cumulative release notes for everything.


   This directory contains example source code and makefiles used in
   testing the installation of the compiler.  The source code in
   this directory is all public domain, and may be copied into your
   own programs at will.  Each of the example programs listed below
   has a makefile associated with it, and in some cases, custom
   header files and RSC files.  The example programs are:

      HELLO.C       The obligatory Hello World program.
      FPMATH.C      Some tests using floating-point math.
      MINICOLR.C    An example that runs as an accessory or program.
      WINDXMP2.C    A GEM program with a window and some neat stuff.
      FORMDEMO.C    A GEM program that uses all the cool new GemFast
                    dialog functions.
      BROWSE.C      A GEM program that uses manages multiple windows
                    and demonstrates handling scrolling windows.
      MAKEFILE.MAK  A makefile which calls MAKE recursively to       
                    compile all the sample programs.

5.0 Credits and Disclaimers

   This version of HSC is released on an as-is basis, under the
   terms of the original Sozobon, Ltd. copyright, which still
   applies.  This is a modified version of Sozobon C, but that does
   not imply any loss or reduction of rights to the original
   copyright holders.  The authors assume no responsibility for the
   consequences of using this software, including, but not limited
   to, responsibility for your mental health. No warranties of any
   sort, express or implied, are made about this software or its
   suitability for a particular purpose.  Besides, I ain't got no
   money, so suing me would be a real waste of your time.

   The original Sozobon C was created by Tony Andrews, Johann Ruegg,
   and Joe Treat.  This modified version was done by Ian Lepore. 
   The dlibs runtime library was done by Dale Schumaker.  Beta
   testing of this modified release was done by Bob Goff, Mike
   Dorman, Steve Yelvington, Scott Bigham, and probably others
   who've I've forgotten about since this release has been lying
   dormant for 6 months now due to extreme laziness (and a being a
   bit busy) on my part.  I want the world to be well aware that a
   lot effort by  a lot of folks went into this project before I
   ever got my hands on  it.  Without them, it wouldn't have been

   Everything in this distribution package which is wholly my own
   work (GemFast, GEMENV, STMAKE, and the example source code) is
   hereby placed into the public domain.  You may copy, modify,
   distribute, or otherwise use these portions of the work in any
   way you please, including their inclusion into other works,
   public domain or commercial.  In particular, I'd like to see
   GEMENV get wide distribution.  If you do modify and redistribute
   any of my works, I'd appreciate it if they are clearly marked as
   modifications, so I won't go nuts trying to support something
   that's been customized.

   This release of HSC is being distributed initially via the BIX
   online system, and I will do my best to provide what support I
   can on BIX.  I'm not consitantly available on any of the other
   networks at this time.  Other than the fact that I hang out
   there, there is no official connection between BIX and this
   software, however.  

   (For you internet'ers:  you may be able to reach me at
   "ianl@bix.com".  The internet mail gateway isn't available yet,
   but I feel certain that it will become available sometime soon. 
   I have no reason to feel that way, other than that GVC management
   at BIX has been doing a good job of upgrading the system lately. 
   If it doesn't work this week, try again next week, and so on
   until it gets through.)

   Oh--and in case you ever wondered:  Sozobon is No Bozos,

   -  Ian Lepore (BIX userid 'ianl')   
      Moderator, BIX atari.st and c.language conferences.

(end of document)

Back to C