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:
- The core run-time that can be used to run ICI scripts
from the command line (or loaded dynamically by other
programs).
- 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.
-
Update and commit everything on all machines.
-
Rebuild the core API documentation MML file that
is extracted from the core source by going to
doc/book and running ici extract-doc-from-src.ici
-
Use FrameMaker to open the book, update it, and regenerate doc/ici.pdf.
-
Check and update the ICI_VER* version numbers in fwd.h.
-
Update the version string in conf.c.
-
Write some release notes to be pasted into the release note area
at SourceForge associated with the release. (You'll also paste in
the change log.)
-
Using MS Visual C, build 'ici4', 'ici4sdk', and 'ici4install' and test
install the core and the SDK. Test with test/tst-all.ici.
-
Test and install the Linux build.
-
Examine Makefile.dist and adjust things if necessary. Especially the
release number.
-
Use make -f Makefile.dist dist-gz to make a distribution.
-
Unpack it somewhere and build and test under both Linux and Windows.