home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ARM Club 3
/
TheARMClub_PDCD3.iso
/
hensa
/
languages
/
icon_1
/
DOCS
/
IPD249_DOC
< prev
next >
Wrap
Text File
|
1995-12-01
|
24KB
|
793 lines
Building Version 9 of Icon for MS-DOS
Ralph E. Griswold
Department of Computer Science, The University of Arizona
The implementation of Version 9 of Icon includes both an
interpreter and an optimizing compiler. The interpreter and com-
piler are largely compatible and almost all Icon programs will
run under either, although some features require the specifica-
tion of options when used with the compiler [1]. The interpreter
is appropriate for program development and many production appli-
cations. The compiler can be used to get faster execution speeds
and a stand-alone executable file that can be distributed without
the interpreter.
Note: This document is primarily concerned with building Icon
for MS-DOS, but the source code also can be used to build Icon
for OS/2; see [2].
1.__Requirements
Processors
Version 9 of Icon runs on computers with 8086/88/x86-family
processors. IBM hardware compatibility is not required. Either
MS-DOS or PC-DOS, Version 3.0 or higher, is needed. The inter-
preter requires at least 500KB of conventional memory to run
satisfactorily. The Icon compiler requires a 32-bit processor
with at least 4MB of RAM. A fast 486 with considerably more RAM
is recommended. The Icon compiler generates C code, which then
must be compiled and linked using the C compiler under which the
Icon compiler was built.
C_Compilers
The implementation is written almost entirely in C and RTL
[3], a superset of C for which a translator to C is supplied.
Building the interpreter is straightforward and can be done on
a 16-bit platform with most of the popular C compilers that sup-
port the large memory model. Building the interpreter requires
at least 510KB of free RAM. If there is not sufficient memory,
MS-DOS may hang. If this happens, you may need to remove some
memory-resident programs to build Icon. Building the compiler
requires a 32-bit C compiler. The amount of RAM required depends
on the compiler. 4 MB is typical.
To date, the Version 9 interpreter for Icon for MS-DOS has
been successfully built using the following C compilers:
IPD249 - 1 - December 1, 1995
Borland C++ 3.0
Intel Code Builder 1.0
Microsoft C 6.0
Microsoft C 7.0
Turbo C 2.0
Watcom C/396 9
Zortech C++ 3.0
The Version 9 compiler for Icon has been successfully built using
Intel Code Builder 1.0
Watcom C/396 9
Zortech C++ 3.0
Version 9 also has been configured for Metaware High C 2.3, but
this configuration has not been tested. The use of a C compiler
not listed here involves additional work to provide appropriate
conditional code.
Assembly_Language
Icon's co-expressions require an assembly-language context
switch. An appropriate assembler therefore is necessary to pro-
vide this feature when building Icon entirely from the source
code. However, object files for context switches are provided,
where available, for persons who do not have an assembler. Alter-
natively, co-expressions can be disabled without otherwise
affecting the use of Icon.
Batch_Scripts
Some of the batch scripts for building and testing Icon use
the call command, which allows a batch script to be run from
inside another batch script, with control then returning to the
former one. If you are using an early version of MS-DOS that does
not support call, you will have to decompose the batch scripts
that use it into more elementary ones.
Disk_Space
The material on the distribution diskettes occupies about
4.5MB when unloaded. This amount can be reduced by deleting
files related to the interpreter and to C compilers that will not
be used. About 1.5MB additional space is needed to completely
build and test the Icon interpreter, although it is possible to
get by with less by building incrementally. Building the Icon
compiler requires additional disk space - 3 to 4MB depending on
the C compiler used.
2.__Organization_of_the_Implementation
The source code for Icon is organized in a hierarchy. Files
for various components of Icon are packaged using LHA. A copy of
IPD249 - 2 - December 1, 1995
LHA is included in the distribution. Instructions for unloading
the files are provided on the distribution diskettes.
If the Icon hierarchy is rooted in \icon, the directories
after unloading are:
|-bin------ executable binaries
|
| |-common--- common files
| |
| | |-borland-- Borland C++
| | |-codebldr- Intel Code Builder
| | |-highc---- Metaware High C
|-config---|-msdos----|-msc6----- Microsoft C 6.0
| | |-msc7----- Microsoft C 7.0
| | |-turbo---- Watcom C
| | |-turbo---- Turbo C
| | |-zortech-- Zortech C++
| |
| |-os2------|-cset2-- Cset/2
|
| |-common--- common source
| |-h-------- headers
| |-iconc---- compiler source
|-icon----|-src------|-icont---- translator source
| |-preproc-- pre-processor source
| |-rtt------ run-time translator source
| |-runtime-- run-time source
|
|-tests----|-local---- local test results
|-stand---- standard test results
In the descriptions that follow, path specifications assume that
the Icon hierarchy is unloaded in \icon\bin. If the location is
different for your installation or requires a drive specifica-
tion, interpret the path specifications that follow accordingly.
The distribution diskettes also contain documentation and some
tools that may be useful in building and testing Icon. See the
README files on the distribution diskettes.
Binary_Files
Since rtt.exe cannot be built under all the C compilers that
otherwise support Icon, a copy is included in the distribution.
Several other executable binaries used in various aspects of
building Icon are also included. These executable binaries are
installed in \icon\bin.
Source_Files
The six source-code sub-directories under src contain the fol-
lowing components of Icon:
IPD249 - 3 - December 1, 1995
common files common to different components of Icon.
h header files used by files in the other direc-
tories.
iconc source code for iconc.exe, the optimizing com-
piler.
icont source code for icont.exe, the translator and
linker that converts an Icon source-language pro-
gram into a form suitable for the interpreter.
preproc source code for an ANSI C pre-processor used by
the run-time translator.
rtt source code for rtt.exe, a program used in
translating run-time code to C.
runtime source code for the interpreter, iconx.exe, and
run-time systems for the compiler and interpreter.
Configuration_Directories
In order to simplify the process of compiling Icon under dif-
ferent C compilers, files that are compiler-specific, such as
batch and linker files, are provided in subdirectories of the
config directory. The MS-DOS configurations presently are:
borland Borland C++
codebldr Intel Code Builder
highc Metaware High C
msc6 Microsoft C 6.0
msc7 Microsoft C 7.0
turbo Turbo C
watcom Watcom C
zortech Zortech C++
The use of these configuration directories is described in next
section. Note: Some files contain path information that may need
to be changed for a particular configuration.
3.__Building_Icon_for_a_Supported_Configuration
Before starting to compile Icon, be sure your C compiler is
properly installed and that any paths that it needs are properly
set.
Setting_up_Files
The first step in the compilation process is to set up the
files needed for compilation and linking. If you are using one
of the C compilers mentioned above, there is a batch script in
the top level of the Icon hierarchy (assumed to be \icon here)
IPD249 - 4 - December 1, 1995
whose name corresponds to the C compiler. Running the batch
script performs the configuration. For example, if you want to
configure Version 9 of Icon to compile under Borland C++, just
enter
borland
This batch script copies compiler-specific scripts, source files,
and object files to appropriate places in the source-code hierar-
chy. Note: Some files may not be found during copying for some
compilers. This is normal, since a common copying script is used
and not all configurations have all the files that others do.
A file containing compiler-specific information, status, is
also copied into the top level of the Icon hierarchy. Read this
file before proceeding, since it may contain information about
problems and limitations related to the C compiler.
Configuration_Changes
Once Icon is set up for a specific C compiler, there may be a
few changes you wish to make before building Icon.
Co-Expressions: Co-expressions are supported by default on
most platforms. To disable them, add
#define NoCoexpr
to \icon\src\h\define.h.
MS-DOS Functions: There are a few functions specially designed
for using Icon under MS-DOS that are not part of Icon's standard
function repertoire. The functions are described in [4]. These
functions normally are included if they are supposed for the C
compiler used. If you wish to eliminate them (which decreases
the size of iconx by a few thousand bytes), remove
#define DosFncs
from \icon\src\h\define.h.
Large Integers: Icon has facilities for large-integer arith-
metic, but these facilities normally are disabled for 16-bit MS-
DOS platforms because they increase the size of iconx substan-
tially (20-30KB). If you have enough RAM and wish to enable
large-integer arithmetic, remove the following line from
\icon\src\h\define.h:
#define NoLargeInts
Directory Path: The icon compiler, iconc.exe, needs to know
where certain files are located. For most C compilers used to
build iconc.exe, this path can be patched after iconc.exe is
IPD249 - 5 - December 1, 1995
built. In some cases, however, this is not possible because of
the format of executable files. See the file status mentioned in
the preceding section.
In cases where patching does not work, it is necessary to
decide in advance where the files needed by iconc.exe will be
located and to place a definition for RefPath in
\icon\src\h\define.h. For example, if the location will be
c:\dos, the definition would be
#RefPath "c:\\dos\\"
Note that the string must end in a backslash.
Use_of_the_Make_Utility
The instructions for building Icon in the next section specify
the use of batch scripts. A public-domain UNIX-style make util-
ity is included in this distribution. It is unloaded into
\icon\bin as make.exe. To use it, move it to a place on your
PATH or add \icon\bin to your PATH.
Makefiles are installed when files are set up for a specific C
compiler. You may find it convenient to use make, especially if
you modify the Icon source code. Be aware, however, that building
Icon from Makefiles requires more RAM than building Icon from
batch scripts. This may cause problems in some situations.
Makefiles also are not available for some steps, either because
some programs malfunction when run under make or because files
are constructed on the fly and their names cannot be determined
in advance.
Compilation
The steps in building Icon follow. Note that the first three
steps refer to building the interpreter, while the last two refer
to the compiler. If you only want to build the interpreter, stop
after Step 3.
The directories mentioned in the following steps are relative
to \icon\src.
1. First cd common and run the batch script build. This
creates object files used in the various components of
Icon.
2. Next cd ..\icont and run the batch script build. This
builds icont.exe and installs it in \icon\bin.
3. Next cd ..\runtime and run the batch script build. This
builds iconx.exe and installs it in \icon\bin. Note:
Problems with insufficient RAM are most likely to occur
at this step. If the build fails for lack of space or if
MS-DOS hangs, reboot with fewer memory-resident programs.
IPD249 - 6 - December 1, 1995
Subsequent steps apply to building the Icon compiler and its
support files. As mentioned above, a 32-bit C compiler is
required for this.
4. First cd ..\iconc and run the batch script build. This
builds iconc.exe and installs it in \icon\bin.
5. This step builds files needed by iconc.exe. A 386 or
higher and at least 4MB of RAM are required. Two of the
batch scripts assume the Icon interpreter is installed in
\icon\bin as built by Steps 2 and 3 above. cd ..\runtime
and run the following batch scripts:
header (creates a header and an object file needed by iconc.exe)
icontrns (creates C files and a database needed by iconc.exe*)
iconcomp (creates object files**)
iconlibe (creates a library needed by iconc.exe*)
The files needed by iconc.exe are copied to \icon\bin.
The scripts flagged with * take a long time. The script
flagged with ** takes a very long time. The time depends not
only on processor speed but also on the compiler used.
4.__Installing_Icon
After performing the steps specified in the preceding section,
\icon\bin should contain the components of Icon indicated above.
To use Icon, the executable files need to be available via
PATH. You can add \icon\bin to PATH or move the executable files
to a place already on PATH.
iconc.exe needs to know the location of two files that are
initially installed in \icon\bin. The files are:
rt.db a database of information about Icon operations
rt.h a header file specified in the code iconc.exe produces
In addition, the following files are needed for linking the
object files that result from compiling the C files produced by
iconc.exe:
rt.lib an object library that contains run-time operations
dlrgint.obj a stub for large integers (if large integers are not supported)
If these four files are moved, they should all be placed in the
same directory.
iconc.exe is initially configured to expect its files in the
directory from which it is executed. In order to be able to run
iconc.exe from any location, a path in it must be patched. The
IPD249 - 7 - December 1, 1995
program patchstr.exe, in \icon\bin, performs this task. It is
used as follows:
patchstr iconc.exe directory-path\
where directory-path is the full path to the directory in which
the four files mentioned above are located. Note that the path
specification must be followed by a backslash.
For example, if the files that iconc.exe needs are not moved,
the patch step would be
patchstr iconc.exe \icon\bin\
The patching process can be repeated as necessary if the
directory is moved.
5.__Running_the_Icon_Compiler
Please note: Running the compiler requires significant
resources and it may not be practical on slow processors or plat-
forms with limited amounts of memory. Furthermore, it may be
necessary to reconfigure your memory extender so that iconc.exe
can use all available RAM.
The use of the compiler under MS-DOS differs somewhat from the
description given in [1], since some of the operations iconc.exe
performs under other operating systems are not practical under
MS-DOS. Specifically, the C files produced by iconc.exe are not
compiled automatically and subsequently deleted. Instead, these
operations must be done after iconc.exe is run.
A batch script, icomp.bat, for using the Icon compiler, is
installed in \icon\bin. A typical version is:
iconc %2 %3 %4 %5 %1
icc %1.c \icon\bin\rt.lib
del %1.c
del %1.h
The first argument is the name of the Icon program (without the
.icn extension). The remaining arguments are provided for
options to iconc. Note that the path for rt.lib needs to be
changed if this file is moved as described in the preceding sec-
tion.
For example, to compile hello.icn with no options, use
icomp hello
while to compile hello.icn with no optimizations, use
IPD249 - 8 - December 1, 1995
icomp hello -na
Note that options follow the program name. See [1] for other
options.
Note: If you are using more than one C compiler, be careful
that the C compiler used to compile the output of iconc.exe is
the same as the one used to build rt.lib and the other files used
by iconc.exe.
6.__Testing_Icon
The following files are required to test Icon:
compare.exe comparison utility
icomp.bat Icon compiler script (compiler tests only)
iconc.exe Icon compiler (compiler tests only)
icont.exe Icon translator
iconx.exe Icon interpreter
These files are located in \icon\bin after building Icon. They
need to be available via PATH for the procedures described below.
Note that icomp.bat may need to be edited as described in the
preceding section.
A suite of test programs is provided in \icon\tests. The
expected output of the test programs is in \icon\tests\stand;
\icon\tests\local is provided for local output. The ``standard''
output was produced by Intel Code Builder. Note: The tests pro-
vided are extensive, but they are not exhaustive.
The directory tests contains several batch scripts for testing
Icon. The ones for testing the interpreter are:
intrcoex.bat co-expressions (if supported)
intrlarg.bat large-integer arithmetic (if supported)
intrmain.bat other features
There are corresponding scripts for testing the compiler:
compcoex.bat co-expressions (if supported)
complarg.bat large-integer arithmetic (if supported)
compmain.bat other features
These scripts report differences between ``standard'' and
local output. Due to compiler or configuration differences,
local output will differ in some cases from the output in stand.
Test output from 16- and 32-bit versions of Icon also may differ
because of different constants used in dynamic hashing and dif-
ferent sizes for storage regions. The string representation of
floating-point numbers also various among different C libraries.
Also, tests may fail because of inadequate RAM, in which cases
IPD249 - 9 - December 1, 1995
the differences shown may be large.
In the case of differences that appear to be abnormal, look at
the corresponding .icn file for a possible explanation.
Note: Running all the interpreter tests takes a long time.
Running all the compiler tests takes a very long time. If you
are building Icon using a compiler for which Icon has been built
before, you may wish to limit your testing to a few programs. The
scripts compsamp.bat and intrsamp.bat are provided for this pur-
pose.
7.__Configuring_Icon_for_a_Non-Supported_C_Compiler
If you want to build Icon under a C compiler for which there
presently is no configuration, set up a configuration directory
for it and copy files from a configuration that is similar to
your C compiler. See [5] for information on modifying the new
configuration to suit your C compiler.
If you are successful in building Icon with the new compiler,
please send the configuration files and any changed source files
to the Icon Project as described in Section 10 so that they can
be incorporated in future releases.
8.__The_Implementation_Book
If you are interested in the larger view of the implementation
of Icon, or if you are interested in modifying or extending Icon,
you may want to acquire the book on the implementation [6]. This
book, which can be purchased from the Icon Project, concentrates
on the run-time system and covers data structures, the virtual
machine, the interpreter, the implementation of generators, and
storage management.
The implementation book corresponds to Version 6 of the Icon
source code. There have been several changes in the source code
between Version 6 and the present version. Supplementary documen-
tation describing these changes is available free of charge from
the Icon Project. Ask for [7-9].
9.__Trouble_Reports_and_Feedback
If you run into problems, contact the Icon Project:
IPD249 - 10 - December 1, 1995
Icon Project
Department of Computer Science
The University of Arizona
P.O. Box 210077
Tucson, AZ 85721-0077
U.S.A.
(520) 621-6613 (voice)
(520) 621-4246 (fax)
icon-project@cs.arizona.edu
We cannot guarantee to solve your problems, but we will try.
We also may be able to place you in contact with other persons
who are compiling Icon and who may have similar problems.
Please also let us know of any suggestions for improvements to
the compilation process and its documentation.
Acknowledgements
Many persons have been involved in the implementation of Icon.
Clint Jeffery and Gregg Townsend collaborated with the author on
Version 9.
References
1. R. E. Griswold, Version 9 of the Icon Compiler, The Univ. of
Arizona Icon Project Document IPD237, 1995.
2. R. E. Griswold, Building Version 9.0 of Icon for OS/2, The
Univ. of Arizona Icon Project Document IPD260, 1994.
3. K. Walker, The Run-Time Implementation Language for Icon, The
Univ. of Arizona Icon Project Document IPD261, 1994.
4. R. E. Griswold, Version 9.0 of Icon for MS-DOS, The Univ. of
Arizona Icon Project Document IPD247, 1994.
5. G. M. Townsend, R. E. Griswold and C. L. Jeffery, Configuring
the Source Code for Version 9 of Icon, The Univ. of Arizona
Icon Project Document IPD238, 1995.
6. R. E. Griswold and M. T. Griswold, The Implementation of the
Icon Programming Language, Princeton University Press, 1986.
7. R. E. Griswold, Supplementary Information for the
Implementation of Version 8 of Icon, The Univ. of Arizona Icon
Project Document IPD112, 1995.
8. R. E. Griswold, Supplementary Information for the
Implementation of Version 9 of Icon, The Univ. of Arizona
Icon Project Document IPD239, 1995.
IPD249 - 11 - December 1, 1995
9. K. Walker, The Run-Time Implementation Language for Version
8.7 of Icon, The Univ. of Arizona Tech. Rep. 92-18. July
1992.
IPD249 - 12 - December 1, 1995