# Release Notes for Version 9.5 of Icon

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

www.cs.arizona.edu/icon/v950/relnotes.htm
Last updated April 12, 2010

## Introduction

Version 9.5.0 of Icon is an update of version 9.4.3 of Icon. It incorporates configuration, documentation, and library changes. Some minor bugs have been fixed. Support has been added for "external values" created by user C functions.

## Changes in version 9.5

Notable changes in this latest version are listed here. Some code cleanup work and documentation editing has also been done.

### External Values

External code incorporated by `loadfunc()` can now create and return to Icon code opaque values that can be stored and passed on subsequent calls. This is similar to a feature of the early Macintosh ProIcon implementation. See External Values for more information.

### Build Environment

This version of Icon is the first to deliberately move beyond the 1989 C standard and make use of features of the 1999 C standard, specifically the "struct hack". Consequently, a C99 (or newer) compiler is now required to build Icon.

### Cygwin Configuration

The `cygwin` configuration has improved, partially through removal of unneeded special cases now that Cygwin better approximates Unix. External functions can now be loaded using `loadfunc()`.

In addition to the `cygwin` configuration, which uses Windows graphics, there is now a new `xcygwin` configuration that uses the X window system.

### Implementation Cleanup

Large amounts of conditionalized dead code, including the old Icon compiler, have been removed from the source code.

All platforms now use POSIX threads for context switching instead of system- and processor-dependent assembly language code.

### Minor Fixes

The `loadfunc()` implementation now specifies to the system that C globals are to be shared with and among loaded functions.

The command `icon nonexistent.icn` no longer leaves debris in the /tmp directory.

The maximum length of a file name has been increased from 256 to 512 characters.

Table copying in the Sparc (Solaris) configuration was fixed by coding a workaround to avoid a GCC 4.2.2 struct assignment bug.

### Library changes

As usual, some files in the Icon program library have been added or edited, but the core library files remain stable. Notable changes include:

    procs/echo	New procedure for interpolating variables in strings.
    procs/printf	Rewrite parts to fix several bugs, and add test.
    procs/random	Improve thoroughness of randomize().

    progs/diffsum	Handle output of "cvs diff".
    progs/unclog	Handle CVS branches; fix indentation.
    progs/weblinks	Add option to sort output by referencing page.

    gprogs/breakout	Make the ball large enough to see.
    gprogs/gallery	Treat -wnnn and -hnnn options as *minimums*.
    gprogs/gallery	Handle spaces embedded in JPEG filenames.
    gprogs/kaleid	Add delay to prevent runaway on fast CPUs.
    gprogs/spider	Add shortcuts, opt-in logging, congratulatory display.
    gprogs/trkvu	Limit file legend to onscreen files.
    gprogs/tron	New video game inspired by Tron.

    packs/loadfuncpp	Add C++ interface package.
    packs/icondb	Add MySQL interface package.

    gpacks/weaving	Add "halftone" weaving program htweav.icn.

### Documentation Additions

Two new documentation pages, Loading C functions and External Values, have been added.

## Earlier feature additions

These features appeared in earlier releases of Icon but subsequent to publication of the Icon books.

### Millions of colors

(new with version 9.4.2 of Icon)

Icon's X-windows interface no longer limits each window to 256 colors at one time. Median-cut quantization selects image colors when writing a GIF file.

### Scriptable source files

(new with version 9.4.1 of Icon)

An Icon source file can be made executable under Unix by prefixing it with a comment line

> `#!/usr/bin/env icon`

and setting its execute permission bit. This uses a new `icon` command, which in another form allows a small Icon program to be embedded within a shell script. See the man page for details. The traditional `icont` command remains available when more flexibility is needed.

### Path searching

(new with version 9.4.0 of Icon)

Under Unix, colons (`:`) may now separate directories in the `LPATH` and `IPATH` environment variables as an alternative to spaces. The Icon translator and linker search these paths when looking for `$include` and `link` files respectively.

The Icon program library is now searched automatically, but `LPATH` and `IPATH` can still be set to control the search order. The effective path in each case is:

1. The current directory
2. Any directories named by the environment variable
3. The Icon library directory

Other changes affect the configuration of Icon at installation time and the way executable Icon programs locate the interpreter. These changes, which are transparent to most users, are discussed in more detail on the File Organization page.

### Reading directory contents

(new with version 9.3.2 of Icon)

The files in a directory can be listed by opening the directory as a file. Subsequent reads return the names of the files contained in the directory. The names are returned in no particular order, and for Unix, the directories `"."` and `".."` are included.

### Reading foreign text files

(new with version 9.3.1 of Icon)

The function `read()` recognizes three kinds of line terminators when reading a file opened in translated mode: Windows (CR+LF), Macintosh (CR), or Unix (LF). Consequently, text files created on one platform can be read by an Icon program running on a different platform.

## Limitations, bugs, and problems

Large integers cannot be used with `i to j`, with `seq()`, or with integer-valued keywords.

Large-integer literals are constructed at run-time, so such literals are best kept outside of loops.

Conversion of a large integer to a string is quadratic in the length of the integer. Conversion of a very large integer may take a long time.

An "evaluation stack overflow" can occur when a procedure is called with a huge number (thousands or more) of arguments. The capacity can be increased by setting the environment variable `MSTKSIZE` or `COEXPSIZE`, as appropriate.

Stack overflow checking uses a heuristic that is not always effective. Stack overflow in a co-expression is especially likely to escape detection and cause a mysterious program malfunction.

Pathologically nested structures can provoke a memory or segmentation fault during garbage collection by reaching the stack limit. The stack limit can be raised by the `limit` or `ulimit` shell command.

If an expression such as `x := create expr` is used in a loop, and `x` is not a global variable, uncollectable co-expressions accumulate with each iteration. This problem can be circumvented by making `x` a global variable or by assigning a value to `x` before the create operation, as in

> `x := &null
> x := create expr`

Integer overflow on exponentiation may not be detected during execution. Such overflow may occur during type conversion.

## Documentation

See the documentation guide for an overview of the available Icon documentation.

For installation instructions, see Installing Binaries or Building from Source as appropriate.

## Acknowledgments

Carl Sturtivant inspired and participated in the development of external values. He also contributed the `loadfuncpp` and `icondb` packages. Eduardo Ochs contributed the `tron` game. Charles L. Hethcoat III contributed the `echo` procedure. Carl Sturtivant and Steve Waldo supplied numerous Cygwin improvements. Cheyenne Wills improved the flexibility of the configuration process. Clint Jeffery fixed an ancient linking bug. Robert Shiplett and Jonathan Kaye helped with testing.