# Porting the Icon Implementation

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

www.cs.arizona.edu/icon/v951/port.htm
Last updated March 25, 2010

## Introduction

This document describes how to port a source release of Icon to a new platform. It assumes familiarity with the process by which Icon is built from source using an existing configuration.

## Requirements

Icon expects the underlying system to conform to certain standards that are met by most modern systems. These are not necessarily the latest standards but rather versions that have already been widely implemented. Newer standards maintain compatibility and present no problems.

### POSIX Commands

Icon is build using Makefiles and shell scripts, as defined by POSIX.2 (IEEE 1003.2-1992). Additionally, Icon uses Makefile includes, which are provided by nearly all modern Unix systems although they are not part of the 1992 standard.

### C Compiler

Icon requires a production-quality compiler supporting C99 (ISO/IEC 9899:1999). Production quality implies correctness, robustness, and the ability to handle large files and complicated expressions.

### C Data Sizes

Icon places the following requirements on C data sizes:

- chars must be 8 bits.
- ints must be 16, 32, or 64 bits.
- longs and pointers must be 32 or 64 bits.
- All pointers must be the same length.
- Pointers and longs must be the same length.

If your C data sizes do not meet these requirements, do not attempt to configure Icon.

### POSIX Library

In addition to the standard C library, Icon uses the library functions specified by POSIX.1 (IEEE 1993.1-1996). In particular, Icon uses POSIX threads and semaphores to implement context switching for co-expressions.

## The Porting Process

Every different Icon configuration has its own subdirectory in the `config` directory of the Icon source tree. To add a new configuration, create a new directory and copy in the `define.h`, `Makedefs`, and `status` files from the `posix` configuration directory.

The porting process involves repeating these steps until the system is working:

1. Edit the configuration files as described below.
2. Configure: `make Configure name=`newdirectory
3. Build: `make`
4. Test: `make Test`

If a configuration parameter is changed it is necessary to reconfigure and rebuild from the beginning.

The Icon source code has proven to be robust and portable. Most porting problems are related to command options and library locations, the things that are configured in the `Makedefs` file.

If the system builds smoothly, but problems are revealed by `make Test`, try removing any C optimization options. New compilers are often stressed beyond their capabilities by Icon.

It is best to start by building just the basic Icon system. When that is working, repeat with `make X-Configure` instead of `make Configure` to build Icon with graphics. (Note that `make Test` does not test graphics, and so you should also execute `bin/colrbook` as an additional manual test.) Finally, when those configurations are working, you may wish to enable dynamic loading as described in a later section.

## Configuration Parameters

Icon is set up by editing three files in the configuration directory of a particular platform. You can examine the files in other directories to see working examples. After a configuration file is changed, Icon must be reconfigured and rebuilt from the beginning (step 2 above). These instructions assume that you are starting from copies of the `posix` configuration files.

### `define.h`

Edit the comment at the beginning of `define.h`, but otherwise leave this file alone. Although some older configurations may define additional values, they are not needed here.

### `Makedefs`

The critical configuration work is done by editing the `Makedefs` file. The parameters set here are:

> `CC`
>   The command name for the C compiler. Typical values are `cc`, `gcc`, or `c99`.
> `CFLAGS`
>   C compiler flags. A path specification for the X11 libraries is usually needed. Include `–O` to optimize the C code, but remove it if it causes problems.
> `CFDYN`
>   C compiler flags for generating dynamic libraries, usually a flag that generates position-independent code. A typical value is `–fPIC`.
> `RLINK`
>   General runtime libraries. Many systems require `–lm` to link the math library. Some systems also require `–ldl` to link `dlopen()`.
> `TLIBS`
>   Thread library. Some systems require `–lpthread` or other values (see examples in other configurations) to link the threads library.
> `XLIBS`
>   Linker specifications for the X Windows library. Many systems need both a path and a library name here.
> `XPMDEFS`
>   Definitions for building the XPM library. Change this (see other examples) if problems occur while building the `src/xpm` directory.
> `GDIR`
>   Leave this alone.

### `status`

The `status` file is not used by the build process, but it should be edited to document the target platform, and it should be updated whenever the configuration changes.

## Dynamic Loading

Icon's optional dynamic loading facility allows Icon programs to call specially written user C code via the built-in `loadfunc` procedure. Dynamic loading is enabled by

1. Editing `config/`name`/define.h` to add `#define LoadFunc` at the end.
2. Editing `ipl/cfuncs/mklib.sh` to add a new case to the shell script that builds a shared library from a set of C object files.
3. Reconfiguring, rebuilding, and retesting as usual. If dynamic loading is enabled in `define.h`, it is tested by `make Test`.

The second step is the hardest; on many systems, documentation that discusses shared libraries is scant or nonexistent.

If problems are found while building, check especially the definitions of the `Makedefs` parameters `CFDYN` and `RLINK`.

## Feedback

Please let us know if you complete a port to a new platform. Review the `status` file one last time and make sure it is correct. Send the files from the new configuration directory (and also `mklib.sh`, if changed) to icon-project@cs.arizona.edu. Please also tell us the values reported on that platform by the `uname -p` and `uname -m` commands.