Welcome to Ian's Heat-and-Serve C!
This release is version 1.40, dated 12/10/92
***************************************************
* THIS IS A MODIFIED VERSION OF SOZOBON C! *
* *
* 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. *
***************************************************
CONTENTS
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,
though.
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
follows:
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:
GEMFBIND.DOC GEMF_V17.DOC GEMUTIL.DOC GEMXTEND.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
disk.
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
bypassed):
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
installation.
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
GEMENV.)
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
files).
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:
PATH=C:\;x:\SOZOBON\BIN\
INCLUDE=x:\SOZOBON\INCLUDE\
LIB=x:\SOZOBON\LIB\
BUFSIZE=4096
TMP=r:\
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
structure:
drive:
\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.
\SOZOBON\BIN
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.
\SOZOBON\INCLUDE
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.
\SOZOBON\LIB
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.
\SOZOBON\DOC
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
pieces.
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.
\SOZOBON\EXAMPLES
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
possible.
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,
backwards.
- Ian Lepore (BIX userid 'ianl')
Moderator, BIX atari.st and c.language conferences.
12/10/92
(end of document)