Installing Version 9 of Icon on UNIX Platforms

Gregg M. Townsend, Ralph E. Griswold, and Clinton L. Jeffery

Department of Computer Science
The University of Arizona
Tucson, Arizona

IPD243c
November 29, 1996

----------------------------------------------------------------------------

1. Introduction

Version 9 [1] is the current version of Icon, superseding Version 8. Version
9 contains new features and major changes to the implementation. This report
provides the information necessary to install Version 9 of Icon on computers
running UNIX.

The implementation of Icon is designed so that it can be installed, largely
automatically, on a variety of UNIX platforms. This is accomplished by
configuration information that tailors the installation to specific
platforms.

The distribution contains configuration information for many UNIX platforms.
These are listed in the appendix. Some of these originated under earlier
versions of Icon. The platforms marked with an asterisk in the appendix have
been tested under Version 9. Installation on a tested platform should be
routine, although minor configuration adjustments may be necessary for local
conditions.

If there is configuration information for your platform, you may be able to
install Icon without modification, but if problems show up, you may have to
modify configuration files [2]. In some cases, there may be partial
configuration information. If the configuration information for your
platform is partial or lacking altogether, you still may be able to install
Version 9 of Icon by providing the information yourself, using other
configurations as guides.

If your platform is not listed in the appendix, it may have been added since
this report was written. See Section 2 for information on how to check for a
configuration for a specific platform.

2. The Installation Process

There are only a few steps needed to install Icon proper. In addition to the
Icon translator and interpreter, there are three optional components that
you can install: a compiler [3], a variant translator system [4], and a
program library [5]. You may want to review the technical reports describing
these optional components before beginning the installation. In any event,
the installation of optional components can be done separately after Icon
itself is installed.

There are Makefile entries for most steps. Those steps are marked by
asterisks. Steps that are optional are enclosed in brackets:

     1.    Decide where to unload Icon.
     2.    Unload the Icon hierarchy at the selected place.
     3*    Check the status of the configuration for your system.
     4*    Configure the source code for your system.
     5*    Compile Icon.
     6*    Run simple tests.
     [7*]  Run extensive tests.
     [8*]  Run benchmarks.
     [9.]  Install Icon at the desired place.

Step 1: Deciding Where to Unload Icon

You can build Icon at any place you wish. The executable binaries can be
moved to another place later.

In the balance of this report, relative paths and the location of files are
given with respect to the location at which the Icon hierarchy is unloaded.
For example, a reference to make is with respect to the Makefile at the top
level of this hierarchy.

Step 2: Unloading the Files

The distribution consists of a hierarchy, which is rooted in ".". Icon is
distributed in a variety of formats. It requires about 20 MB of disk space
when unloaded. The amount of space it takes to build Icon depends on the
platform, what components are built, and whether intermediate files are
deleted between building components.

If the root of the Icon hierarchy is icon, the resulting hierarchy should
look like this after the distribution files are unloaded:

          |-bin------              executable binaries and support files
          |
          |-config---|-unix------  UNIX configuration directories
          |
          |-docs-----              documents
          |
          |-ipl------              Icon program library
          |
          |          |-common----  common source
          |          |-h---------  header files
          |          |-iconc-----  Icon compiler source
|-icon----|-src------|-icont-----  Icon translator source
          |          |-preproc---  preprocessor source
          |          |-rtt-------  run-time translator source
          |          |-runtime---  run-time source
          |          |-vtran-----  variant translator source
          |          |-xpm-------  XPM support
          |
          |          |-bench-----  benchmarks
          |          |-calling---  calling C functions
          |          |-general---  general tests
          |-tests----|-graphics--  graphics tests
                     |-samples---  sample programs
                     |-vtran-----  variant translator tests

There are additional subdirectories that are not shown above.

Step 3: Checking the Status of the Configuration for Your Platform

Check the status of the configuration for your platform before attempting an
installation; it may contain essential information. This can be done by

     make Status name=name

where name is one of those given in the table in the appendix at the end of
this report. For example,

     make Status name=sun4 solaris

lists the status of the configuration for a Sun 4 workstation running
Solaris 2.x.

In many cases, the status information was provided by the person who first
installed Icon on the platform in question. The information may be obsolete
and possibly inaccurate; use it as a guide only.

There are some configurations for which not all features of Icon are
implemented. If the status information shows this for your platform, proceed
with the installation, but you may wish to implement the missing features
later. See Reference 2 for this.

Step 4: Configuring Icon for Your Platform

Configuring Icon creates several files for general use. Before starting the
configuration, be sure your umask is set so that these files will be
accessible.

There are two configuration possibilities: with or without graphics
facilities.

To configure Icon without graphics facilities, do

     make Configure name=name

where name is the name of your platform as described above. For example,

     make Configure name=sun4_solaris

configures Version 9 of Icon for a Sun 4 Workstation, but without graphics
facilities.

To configure Icon with the X Window System graphics facilities, use
X-Configure instead of Configure, as in

     make X-Configure name=sun4_solaris

Note: On some platforms, error exit codes from installation processes may be
intercepted by make and result in warning messages. These messages can be
safely ignored.

If you first configure without graphics facilities and later decide to add
them, you will need to re-install Icon starting with this step.

If errors occur because the X include files or libraries are not found where
they are expected, modify the appropriate files in the subdirectory of
config/unix (see Reference 2) and restart from the make X-Configure step.

Step 5: Building the Icon Interpreter

Next, compile the Icon interpreter by

     make Icon

There may be warning messages on some platforms, but there should be no
fatal errors.

Step 6: Performing Simple Tests

If Icon compiles without apparent difficulty, a few simple tests usually are
sufficient to confirm that Icon is running properly. The following does the
job:

     make Samples

This test compares local program output with the expected output. There
should be no differences. If there are no differences, you presumably have a
running installation of Icon.

Step 7: Extensive Testing

If you want to run more extensive tests, do

     make Test

Some differences are to be expected, since tests include date, time, local
host information, and platform-specific formats for floating-point numbers.
In addition to Test there are some individual tests of optional features.
See the main Makefile for more information about the tests.

To test Icon's graphic facilities, use gpxtest.icn in test/graphics. It
should build and run without error, producing a window similar to the GIF
image gpxtest.gif in the same area.

Step 8: Benchmarking

Programs are provided for benchmarking Version 9 of Icon. To perform the
benchmarks, do

     make Benchmark

See also the other material in the subdirectory tests/bench. It contains a
form that you can use to record your benchmarks with the Icon Project (see
Section 9).

Step 9: Installing Icon

The files needed to run Icon are placed in bin in the Icon hierarchy as the
result of building the Icon interpreter:

     icont Icon translator
     iconx Icon interpreter

Some other files related to installing Icon and the optional components
mentioned earlier also are placed in bin. The executable files needed to run
Icon -- icont and iconx -- can be copied or moved to any desired place, and
they need not be in the same directory.

Since icont must know the location of iconx, it is necessary to patch icont
if iconx is moved. The program patchstr, also installed in bin, is provided
for this purpose. It is used as follows:

     patchstr icont-location iconx-location

For example, if icont is moved to /usr/local/icont and iconx is moved to
/usr/local/icon/iconx, the patching step is

     patchstr /usr/local/icont /usr/local/icon/iconx

Patching can be repeated if necessary. The patch value can be checked by
using patchstr without a second argument, as in

     patchstr /usr/local/icont

which prints the path to iconx in /usr/local/icont.

3. Installing the Compiler

In addition to the interpreter, whose installation is described above, there
is a compiler. The interpreter gets a program into execution quickly and is
recommended for program development, debugging, and most production
situations. The compiler produces code that executes somewhat faster than
interpreted code (a factor of 2 or 3 is typical), but the compiler requires
a large amount of resources and is very slow in producing executable code.
The compiler is recommended only for small programs where execution speed is
the paramount concern.

The interpreter and compiler are independent of each other and can be built
or rebuilt separately. You can skip this section if you do not need the
compiler.

Installing the compiler is very similar to installing the interpreter. Steps
1 through 4 in Section 2 apply to both the interpreter and compiler and need
be done only once.

For subsequent steps, there are Makefile entries that are the same as for
the combined installation, but with the suffix -iconc to distinguish the
compiler. The steps to build the compiler are:

     make Icon-iconc
     make Samples-iconc
     make Test-iconc
     make Benchmark-iconc

Note: When testing the Icon compiler in conjunction with some C compilers,
it may be necessary to remove the options -p -w for suppressing warning
messages that appear in icon/tests/general/Makefile. The file iconc needed
to run the Icon compiler is placed in bin in the Icon hierarchy as the
result of building Icon. Files needed by iconc also are placed in bin:

     dlrgint.o   stubs for large integer arithmetic
     libXpm.a    XPM library if configured for graphics
     rt.a        compiler library
     rt.db       compiler database
     rt.h        include file

The executable file iconc can be moved to any place. Similarly, the files
needed by iconc can be moved to another directory. There is a Makefile entry
for doing this:

     make CopyLib Target=directory

where directory is the directory in which the files needed by iconc are to
be placed.

Since iconc must know the location of the files it uses, it is necessary to
patch iconc if the files it needs are moved:

     patchstr iconc-location directory/

where iconc-location is where iconc is located and directory is where the
files that iconc needs are located. For example, if iconc is moved to
/usr/local/iconc and the files needed by iconc are placed in the directory
/usr/local/icon/iconc.lib, the patching step is

     patchstr /usr/local/iconc /usr/local/icon/iconc.lib/

Note that a full path should be used for the directory that contains the
files iconc needs and that this path must be followed by a terminating
slash. The patching of iconc can be repeated if necessary.

The path used by iconc can be checked by using patchstr without a second
argument, as in

     patchstr /usr/local/iconc

4. Variant Translators

The variant translator system facilitates the construction of preprocessors
for variants of the Icon programming language.

The variant translator system requires a version of yacc(1) with large
regions. You may have to tailor your version of yacc(1) for this. If there
is a problem, it will show up during testing.

A script, icon_vt, for creating variant translators, is placed in bin during
the configuration step described earlier. There is no separate step for
building the variant translator system.

For testing, do

     make Test-vtran

There may be warning messages during compilation, but there should be no
fatal errors.

5. Icon Program Library

The Icon program library contains a variety of programs and procedures. This
library not only is useful in its own right, but it provides numerous
examples of programming techniques that may be helpful to novice Icon
programmers. While this library is not strictly necessary for using Icon,
most sites install it, and it is required for all but the most trivial
graphics programs.

In addition to the library proper, the directory ipl/idol contains an
object-oriented version of Icon written in Icon. Go to that directory for
more information.

The Icon program library can be used with both the interpreter and the
compiler. However, its use under the compiler requires command-line options
in some programs to enable features that are not enabled by default when
using the compiler. Because of this problem, the installation of the the
Icon program library is not supported for iconc.

To build the Icon program library, do

     make Ipl

This puts compiled programs in ipl/icode and translated procedures in
ipl/ucode.

To test the library, do

     make Test-ipl

No differences should show.

You can copy the executable programs in ipl/icode and the translated
procedures in ipl/ucode to other places to make them more accessible,
although they can be used from any location that is readable by the user.

6. Installing Documentation

The directory docs contains manual pages:

     icon.1     Icon compiler and interpreter
     icon_vt.1  Icon variant translator

You may wish to copy these manual pages to a standard location for such
documentation. If you are replacing an earlier version of Icon, you should
delete the obsolete manual pages, icont.1, iconc.1, and icon_pi.1.

The docs directory also contains PostScript files for technical reports
related to Version 9 of Icon, including those listed under References.

7. Cleaning Up

You can remove object files and test results by

     make Clean

If you copied components of Icon to other places, you can delete the copies
left in the Icon hierarchy.

You also can remove source files, but think twice about this, since source
files maybe useful to persons studying or modifying the implementation. In
addition, you can remove files related to the option components of the Icon
system that you do not need. If you are tight on space, you may wish to
remove documents as well.

8. Communicating with the Icon Project

If you run into problems with the installation of Version 9 of Icon, contact
the Icon Project:

     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

Please also let us know if you have any suggestions for improvements to the
installation process or corrections or refinements to configuration
information.

Acknowledgement

Cliff Hathaway assisted in the testing and distribution of Version 9 of Icon
for UNIX platforms.

References

1. R. E. Griswold, C. L. Jeffery and G. M. Townsend, Version 9.3 of the Icon
Programming Language, The Univ. of Arizona Icon Project Document IPD278,
1996.

2. 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.

3. R. E. Griswold,Version 9 of the Icon Compiler, The Univ. of Arizona Icon
Project Document IPD237, 1995.

4. R. E. Griswold, Variant Translators for Version 9 of Icon, The Univ. of
Arizona Icon Project Document IPD245, 1994.

5. R. E. Griswold and G. M. Townsend, The Icon Program Library; Version 9.3,
The Univ. of Arizona Icon Project Document IPD279, 1996.

----------------------------------------------------------------------------
Appendix -- UNIX Icon Configurations

Configuration information for the platforms listed below is provided in
Version 9 of Icon. Asterisks identify configurations that have been tested
under Version 9, although some have documented problems.

computer                UNIX system              name

Amdahl                  UTS                      amdahl_uts
Apollo Workstation      BSD                      domain_bsd
Astronautics ZS-1       UNIX                     zs1
AT&T 3B1 (UNIX PC)      System III               unixpc
AT&T 3B2                System V                 att3b_2
AT&T 3B5                System V                 att3b_5
AT&T 3B15               System V                 att3b_15
AT&T 3B20               System V                 att3b_20
AT&T 3B4000             System V                 att3b_4000
AT&T 6386               System V                 att6386
CDC Cyber               NOS/VE                   cdc_vxve
Celerity                4.2BSD                   celerity_bsd
Codata 3400             Unisis                   codata
Convergent MegaFrame    CTIX                     mega
Convex C240             BSD                      convex
Cray-2                  UNICOS                   cray2
*DEC Alpha              OSF/1 Version 3.x        dec_osf
DEC MIPS                Ultrix                   decstation
DG AViiON               System V                 aviion
DIAB                    D-NIX                    diab_dnix
Elxsi-6400              BSD                      elxsi_bsd
Encore                  UMAX                     multimax_bsd
Gould Powernode         UTX                      gould_pn
HP 9000/330             HP-UX                    hp9000_s300
HP 9000/500             HP-UX                    hp9000_s500
*HP RISC                HP-UX                    hp_risc
IBM 370                 AIX                      ibm370_aix
IBM PS/2                AIX                      ps2_aix
IBM RS6000 Workstation  AIX                      rs6000_aix
IBM RT Workstation      ACIS                     rtpc_acis
IBM RT Workstation      AIX                      rtpc_aix
Intel 286               XENIX 286                i286_xenix
Intel 386               BSD/OS 2.0               i386_bsdos
Intel 386               FreeBSD                  i386_freebsd
Intel 386               Linux                    i386_linux
Intel 386               Linux                    ix86_linux_elf
Intel 386               Solaris                  i386_solaris
Intel 386               System V                 i386_sysv
Intel 386               System V/GNU C           i386_sysv_gcc
Intel 386               System V, Release 4      i386_svr4
Intel 386               XENIX 386                i386_xenix
Intel 386               XENIX 386/GNU C          i386_xenix_gcc
Intel 486               FreeBSD                  i486_freebsd_gcc
Intergraph Clipper      System V                 clix
Macintosh               AU/X                     mac_aux
Masscomp 5500           System V                 masscomp
Microport V/AT          System V                 microport
MIPS/r3000              System V                 mips
Motorola 8000/400       System V                 mot_8000
Multiflow Trace         UNIX                     trace
NeXT                    Mach                     next
Plexus P60              System V                 plexus
Pyramid 90x             4.2BSD                   pyramid_bsd
Ridge 32                ROS                      ridge
Sequent Balance 8000    Dynix                    balance_dynix2
Sequent Symmetry        Dynix                    symmetry
Siemens MX500           SINIX                    mx_sinix
*SGI 4D                 Irix                     iris4d
Stride 460              UniStride                stride
Sun 2 Workstation       SunOS                    sun2
Sun 3 Workstation       SunOS                    sun3
Sun 3 with 68881        SunOS                    sun3_68881
Sun 386i                SunOS                    sun386i
*Sun 4 Workstation      SunOS 4.1                sun4
Sun 4 Workstation       SunOS 4.1/GNU C          sun4_gcc
Sun 4 Workstation       SunOS 4.1/Open Windows   sun4_openwin
Sun 4 Workstation       SunOS 4.1/Code Center    sun4_saberc
*Sun 4 Workstation      Solaris 2.x/SunPro C     sun4_solaris
Sun 4 Workstation       Solaris 2.x/Centerline C sun4_solar_clc
Sun 4 Workstation       Solaris 2.x/GNU C        sun4_solar_gcc
Unisys 7000/40          4.3BSD                   tahoe_bsd
VAX-11                  4.1BSD                   vax_41_bsd
VAX-11                  4.2BSD and 4.3BSD        vax_bsd
VAX-11                  System V                 vax_sysv
VAX-11                  Ultrix                   vax_ultrix
VAX-11                  9th Edition              vax_v9

