[Icon home]

File Organization in Version 9.4 of Icon

Gregg M. Townsend
Department of Computer Science
The University of Arizona

Last updated November 8, 2005


Version 9.4 of Icon introduced several changes to the organization of Icon's files under Unix and the methods for finding them. These changes, which are described below, simplify the installation and use of Icon.

Library procedure inclusion

As Icon evolved, the procedures from the Icon program library became more important to basic Icon programs, and vital to graphics programs; yet the IPL had been treated as a separate product. A complete Icon system required two downloads and two installation efforts, with proper coordination.

With Icon 9.4, the complete set of basic and graphics library procedures is included with every binary Icon distribution. Also present are the associated $include files and a selected few programs from the library — notably VIB, the visual interface builder.

Source distributions of Icon 9.4 include the full library, which also continues to be available separately.

Installation directory structure

An Icon binary distribution unpacks to produce an icon directory containing bin, lib, man, and doc subdirectories. Building Icon from source produces these same directories.

The bin directory contains executables of icont, the Icon translator; iconx, the Icon interpreter; a few library programs including vib; and libcfunc.so, the loadable C functions. There is a symbolic link from icon to icont. Files in this directory are system dependent.

The lib directory holds $include files and "ucode" (.u1/.u2) files of program library procedures. This directory is system independent.

The man directory holds the Unix man page for icont, and the doc directory holds HTML (.htm) documentation files. These directories are also system independent.

This structure is similar to that of binary distributions of Icon 9.3. The main difference is that the lib directory no longer holds just a subset of the procedure collection, and the few files from the former include directory have moved into lib.

Installation location

The icon directory can be installed in any public or private area as long as its internal structure is preserved. When upgrading an existing Icon installation, replacing the previous Icon directory with the new one may provide the smoothest transition. Old Icon binaries will continue to function correctly with the new interpreter.

In order to consider packaging Icon binaries in Linux RPM files, or other similar packages, it is necessary to define a "canonical" location for installing Icon. The suggested canonical system installation location for Icon is /opt/icon. The /opt directory is present today on most Unix systems and is the location recommended by the emerging File Hierarchy Standard (FHS), www.pathname.com/fhs.

For convenience of use it may be desirable to provide symbolic links from a directory such as /opt/bin or /usr/local/bin to programs in the Icon bin directory. If this is done, the list should include at least icon, icont, iconx, and vib.

Automatic inference of iconx location

Past versions of icont were configured to know the location of iconx in order to embed this in generated binaries. The iconx location was configured by editing src/h/path.h in source builds or by using the patchstr utility to edit the icont executable when installing a binary distribution.

In version 9.4, icont deduces its own location, and from this it infers the location of iconx in the same directory. No configuration of icont is needed, and the correct path is embedded automatically, requiring only that icont and iconx reside in the same directory.

It is still possible to configure a fixed path in icont using the patchstr utility. If this is done, the configured path is used instead of the inferred path.

Automatic search for iconx at execution

The path that icont embeds in an Icon executable makes binary distributions of Icon programs difficult because the embedded path must be edited to match the installed location of iconx. The ipatch utility performed this task when installing binary distributions of Icon 9.3.

Icon 9.4 implements a simple search in the shell script that heads each generated Icon executable. The new header script searches for iconx in these places:

  1. in the location specified by the ICONX environment variable
  2. in the same directory as executing binary
  3. in a location specified in the script itself (as generated by icont or as patched later)
  4. in the command search path ($PATH)

The second item is the key: If there is a copy of iconx in the same directory as the executing program, it is found automatically and used as the interpreter. An Icon program can now be distributed in binary form simply by including an iconx executable in the same directory as the program executable.

The ipatch utility has been modified to recognize both old and new headers, and can still be used to edit the path embedded in an Icon executable.

Automatic library access

The ability to figure out its own location also lets icont provide automatic access to library procedures. The inferred location of the lib directory is implicitly appended to the paths, if any, specified by LPATH and IPATH environment variables. To use only the standard library files, no environment variables need be set.

In a similar manner, iconx creates or alters the FPATH environment variable before beginning execution of an Icon program. This provides transparent access to the library's loadable C functions without requiring explicit user action.

No Setup step

With the changes above, the executable files in an Icon binary distribution are ready for use without modification. The annoying and error-prone Setup step that was necessary with previous versions is no longer required. With Icon 9.4, installation can be as simple as just unpacking the tar file and adding its bin directory to the search path.