Porting the Icon Implementation

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

www.cs.arizona.edu/icon/uguide/port.htm
Last reviewed March 25, 2010
Minor update May 29, 2016

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 built using Makefiles and shell scripts, as defined by POSIX.2 (IEEE 1003.2-1992). Additionally, Icon uses Makefile includes, which were finally recognized by the standard in 2013.

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:

Edit the configuration files as described below.
Configure: make Configure name=newdirectory
Build: make
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

Editing config/name/define.h to add #define LoadFunc at the end.
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.
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.