Notes on building ICI

This documentation is maintained in hand-crafted HTML in order to allow well-behaved revision control and simultaneous edits by different people. Please don't use WYSIWIG editors. Sorry if that makes it hard.

Contents

Summary of platforms
Platform Makefile Config file Contacts Notes
Windows (All Win32) Makefile.w32 conf-w32.h Tim Long ICI on Microsoft Windows
Linux Makefile.linux conf-linux.h Andy Newman  
BeOS (x86) Makefile.beos conf-beos.h XXX  
BSD Makefile.bsd conf-bsd.h Andy Newman  

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.

ICI on Microsoft Windows

On Windows platforms (any Win32 varient), ICI is compiled into a DLL (Dynamic Link Library) called ici.dll. A definition file (ici.def) is used to specify which identifiers should be externally visible to other programs. Just about everything is, and if something is missing, just add it.

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

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

If wici.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.

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' 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
Don't include the BSD sockets functions (skt.c). Again useful on platforms that don't support or require networking.
NOSYSCALL
Don't include Unix-style system calls (syscall.c). Many of these functions work on Win32 systems too.
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, 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-w32.h"
 is the file used by Windows, 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 must 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.