Notes on building ICI

Contents

Introduction

 The ICI core is designed to build simply and easily on most platforms. This description deals with building the ICI core itself. The extension modules are in a seperate package.

The build process makes two things:

  1. The core run-time that can be used to run ICI scripts from the command line (or loaded dynamically by other programs).
  2. A software development kit (SDK) which can be used to write extension modules (or use ICI as an extension to another program).
For each target configurtion (typically a platform flavour) a different configuration include file is made by copying the closest exisiting one, and adjusting. Each of these files is called conf-xxx.h where xxx is the "flavour". There is typically also a Makefile.xxx to match each of these. (For Windows there is also a Visual C workspace.)

The file ici.h is the main include file for both seperately compiled extension modules and programs invoking the ICI interpreter. It is made by the build process specificly for each different flavour. (Actually, it is made by an ICI script, mk-ici-h.ici, so you must successfully build ICI before you can make ici.h.)

The following table summarises some of the standard configurations for which configuration includes and Makefiles are included in the ICI source. Building on these platforms should be reasonably straightforward.
Platform Makefile Config file Make/build produces Notes
Win32 win32\ici4.dsw or Makefile.w32 conf-w32.h ici4.dll, ici4.lib, ici.h, ici.exe, iciw.exe ICI on Microsoft Windows
Linux Makefile.linux conf-linux.h liblinux.a, ici.linux, ici.h  
BeOS (x86) Makefile.beos conf-beos.h libbeos.a, ici.beos, ici.h  
BSD Makefile.bsd conf-bsd.h ici4, ici.h ICI on BSD Unix
Solaris 2 Makefile.sol2 conf-sol2.h ici.sol2, libsol2.a, ici.h  
MacOSX Makefile.osx conf-osx.h ici4, libici4.a, ici.h ICI on BSD Unix

Building ICI for a supported UNIX-like platform

Building ICI for a supported platform is easy. Simply decide what machine you're on and do a make -f Makefile.$MACHINE (where you replace $MACHINE with the name) to create the library lib$MACHINE.a and the interpreter ici.$MACHINE. For example under SunOS 4.1 we use the name "sun" and Makefile.sun to build libsun.a and ici.sun. Under NeXTSTEP we use Makefile.next etc... To see the list of supported systems it suffices to see what configuration files exist, these files have names in the form conf-$MACHINE.h.

To install the interpreter use make -f Makefile.$MACHINE install. This installs the interpreter, library, manual pages, documentation, header and startup files. See the Makefiles for details.

Manifest of a core install on UNIX-like machines

ICI would usually be installed in /usr/local. From that base, the following forms a core run-time installation: 

bin/ici (linked to bin/ici4)
bin/ici4
include/ici.h
include/icistr-setup.h
lib/libici4.a
lib/ici4/ici.pdf
lib/ici4/ici4core.ici
lib/ici4/ici4core1.ici
lib/ici4/ici4core2.ici
lib/ici4/ici4core3.ici
man/man1/ici.1
man/man1/icifuncs.1
man/man1/icinet.1
man/man1/icioo.1
man/man1/iciops.1
man/man1/icire.1
man/man1/icistmt.1
man/man1/icisys.1
man/man1/icitypes.1

ICI on Microsoft Windows

 On Windows platforms (any Win32 varient), ICI is compiled into a DLL (Dynamic Link Library) called ici4.dll. A definition file (ici.def) is used to specify which identifiers should be externally visible to other programs. The DLL is linked to use multi-threaded DLL based run-time libraries.

There is a Makefile.w32 that can be used to build ICI from the command line using Microsoft Visual C. However, this is no longer used much. A Visual C workspace is located in the win32 sub-directory. See README.txt in that directory for details.

Applications may use the ICI DLL as a run-time component by including the library file ici4.lib in their build (ici4.lib is produced as a side-effect of the build of ici4.dll) and, of course, including relevent include files.

Two other programs, ici.exe and iciw.exe are also built. They are just simple stubs to invoke the DLL. The first (ici.exe) is a console application, the second (iciw.exe) is a window application. They both take command line arguments, but iciw.exe does not support wild-card expansion.

If iciw.exe is copied to another file name, say xxx.exe, and the file xxx.ici exists in the same directory, xxx.ici will be inserted as the first argument as if it had been provided on the command line. This is a kludge to alleviate the lack of #! support under Windows.

Manifest of a core install on Windows

The following forms a core run-time installation: 

*system-dir*\ici4.dll
*system-dir*\ici.exe
*system-dir*\iciw.exe
*system-dir*\ici\ici4core.ici
*system-dir*\ici\ici4core1.ici
*system-dir*\ici\ici4core2.ici
*system-dir*\ici\ici4core3.ici
*system-dir*\ici\ici4widb.dll
*prog-files*\ICI\ici.pdf

ICI on BSD Unix

 The BSD configuration of ICI is intended to be portable to all major variants of BSD 4.4 - FreeBSD, NetBSD, OpenBSD, BSDi and Darwin (Mac OS X). Not all these platforms have been tested although no major problems are expected.

Individual BSD variants require somewhat different build methods, essentially different invoccations of make(1) to work around differences in the implementation of the bsd.prog.mk include file. The reference platform is FreeBSD on which a simple make suffices to build the interpreter and a make install to install it. On other systems extra command line arguments may be required.

Variant Version Make Command Comments
FreeBSD 2.x, 3.x, 4.x, 5.x make The reference BSD platform.
NetBSD 1.4, 1.5 make MANDIR=${PREFIX}/man NetBSD installs manual pages differently to FreeBSD On NetBSD the pages are formatted and the cat version of the page installed. Select ${PREFIX} according to where you install ICI, this is usally /usr/local
OpenBSD 2.7 make No significant differences between OpenBSD and FreeBSD.
BSDi ? make? This configuration has yet to be tested
Darwin (Mac OS X) 10.2.6 make ICI should build "out of the box" on Mac OS X. Previous versions required the dlcompat library but this has been replaced (see the macosx directory in the source distribution).

Configuration

The distributed makefiles build the interpreter with the default configuration for that system. The configuration is controlled by the system's conf-$MACHINE.h file. A configuration defines which language extensions (collections of builtin functions) are included in the build and overcomes some portability concerns. The file conf-sample.h contains a prototype configuration.

Changing the configuration

 To change the configuration you edit the system's `conf-xxx.h' header file and define or undefine macros to include/exclude features. The default macros are listed below. Defining the macro REMOVES the feature from the build (which is why the names all start with "NO"). The macros are:
NOMATH
Don't include mathematical builtins such as the trigonometric functions etc... This is useful on small or embedded systems that do not require these. On most hosted environments (i.e. those with a real OS) it is better to leave these in as you'll want them one day.
NOWIN
Don't include the ICI text windowing functions (the code in win.c). ICI's text windowing provides a simple curses-like environment (but faster and smaller). There is some documentation in the ICI manual page and the source of course.
NODB
Obsolete. Previous versions of ICI supported a text file database package which is no longer included. This name used to control its inclusion.
NOTRACE
Don't include the trace() function or its support code. This function was an attempt to include some kind of debug tracing in ICI but isn't all that useful.
NOWAITFOR
Don't include the waitfor() function. Useful for systems that don't implement BSD's select().
NOPIPES
Don't include pipe support (popen etc.. in clib.c). This is used on systems such as MS-DOS that don't provide this.
NOSKT
Obsolete. Previous versions of ICI included BSD sockets functions in the core. They have now moved to the net extension module.
NOSYSCALL
Obsolete. Previous versions of ICI included Unix-style function in the core. They have now moved to the sys extension module.
NODIR
Don't include the dir() function.
NOPASSWD
Don't include the Unix password file access function.
NOSTARTUPFILE
Don't look for a startup file or provide the -s switch to stop that behaviour.
NODEBUGGING
Don't include the debugging hooks. This may be used to avoid including the debug code and its tests in the execution loop. Might be useful if performance is an issue.
ICI_RAND_IS_C_RAND
If this is defined then ICI's rand() function will be implemented via the C library rand() function otherwise ICI uses its own generator function.
NOEVENTS
Don't include the event processing framework, see events.c.
NOPROFILE
Don't include the profiling support, see profile.c and profile.h.

General notes on building ICI and extensions

 For all systems except MS Windows (for which it is optional), for both ICI main code builds and extension builds, the preprocessor define CONFIG_FILE must be defined to be the name of the ICI configuration file which is specific to the target. The defined value should include double quotes around the name. For example:

"conf-sun.h"
 is the file used by SunOS, and this would be defined on the command line or in the project settings with:
-DCONFIG_FILE=\"conf-w32.h\"

ICI as an extension

We are concerned here with the case where ICI does not supply the main entry point, but is invoked from other code. There are a number build issues involved with this.

Firstly, every one of your source files that references some ICI items must include fwd.h from the ICI source directory, and possibly other includes. It is almost essential that the include search path, for those source files at least, has the ICI source directory on it.

Secondly, those same source files may need to be primed with the definition of the current platform's ICI configuration include file (CONFIG_FILE). See the note on CONFIG_FILE defines.

See ICI on Microsoft Windows for further details of linking ICI into Window's programs.

Some notes on making release

These notes are a checklist of a few things that shouldn't be forgotten when making new releases. They are not a complete recipe.