# File Organization in Icon Installations

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

www.cs.arizona.edu/icon/uguide/files.htm
Last updated November 16, 2009

## Introduction

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.

Now, 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 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` pages for `icon` and `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.

Now, `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 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. Now, installation can be as simple as just unpacking the tar file and adding its `bin` directory to the search path.