Go to the previous, next section.

Installation of ILU

This document describes the installation of version RELEASE_NUMBER of the Inter-Language Unification (ILU) system.

If you succeed in installing ILU on a particular platform, we'd appreciate it if you could send a note to ilu-core@parc.xerox.com telling us (1) what operating system you succeeded with, and what version of that OS, (2) which versions of what compilers you used, and (3) which version of ILU you used. We're accumulating a list of operating systems and compilers that work with ILU. If you had to make any changes to make it work on your system, please send them along, and we'll incorporate them into the next release.

Installing on a UNIX System

Prerequisites

You will need an ANSI C compiler to build and install ILU, along with an ANSI C-compliant `libc.a'. Note that GNU gcc doesn't always work as an ANSI C compiler. The simple test we use to qualify a compiler is whether it can compile and link the following program without warnings or errors:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <limits.h>
int main(int ac, char **av) {
 int i = INT_MAX;
 char *p = (char *) malloc(1048);
 memmove(p, *av, strlen(*av)+1);
 printf("%s %d\n", p, i);
 return 0;
}

ILU requires the imake program from the MIT X Consortium release of the X Window System, version 4 or later. This is available via FTP from the ftp servers ftp.x.org on the East Coast, or gatekeeper.dec.com on the West Coast. You can also get it from@br ftp://ftp.parc.xerox.com/pub/ilu/imake/imake.tar.gz.

ILU normally provides support for a number of languages, currently ANSI C, C++, Modula-3, Python, and Common Lisp (Franz Allegro 4.2, and Harlequin LispWorks), but the 2.0alpha release only contains support for ANSI C, C++, and Python.

• If you wish to build the support for ANSI C, you will need a C compiler, and an ANSI C-compliant libc. But you already need that to build ILU.
• If you wish to build the support for C++, you will need a C++ compiler that conforms to version 2.0 of the C++ specification. ILU does not use either C++ templates or exceptions, as these are too spottily implemented to be relied on. The GNU C/C++ compiler g++ seems to work well with ILU. It has also been tested with Lucid's Energize lcc compiler, CenterLine's CC compiler, and Sun's CC compiler.
• If you wish to build support for Modula-3, you will need to wait for the 2.0beta release.
• If you wish to build the support for Common Lisp, you will need to wait for the 2.0beta release.
• If you with to build support for Python, you will need the Python 1.1.1 (or later) release, available via FTP from `ftp://ftp.cwi.nl/pub/python/'.

For the Impatient

You can try just unpacking it, and typing

% make

at the top of the source tree. A minimal configuration using defaults will be built, sufficient for testing.

Real Configuration

Begin by creating two directories: one, ILUHOME, to install the ILU in, and the other, ILUSRC, to unpack the sources in, and build the system in. It is often convenient if ILUSRC is a sub-directory of ILUHOME, but it is not necessary. At PARC, we use `/import/ilu' for ILUHOME, and `/import/ilu/src' for ILUSRC.

Copy the compressed tar file `ilu-RELEASE_NUMBER.tar.Z' or `ilu-RELEASE_NUMBER.tar.gz' to ILUSRC. Uncompress it if necessary with the uncompress or gunzip program:

% uncompress ilu-RELEASE_NUMBER.tar.Z

or

% gunzip ilu-RELEASE_NUMBER.tar.gz

Then unpack the tar file:

% tar xf ilu-RELEASE_NUMBER.tar

ILU uses the GNU autoconf system to configure the release, before building. The very simplest way to configure your system is type type

% ./configure

at the top of the source tree.

What will happen is that ILUSRC/imake/configure will go out and look along the value of your PATH environment variable for various executable programs. If it finds cc, it will assume that you want to build ANSI C support for ILU. If it finds m3, it will assume that you want to build Modula-3 support for ILU. If it finds cl or franz, it will assume that you want to build Lisp support for ILU. If it finds python, it will assume that you want to build Python support for ILU. If it finds CC or cxx or c++, it will assume that you want to build C++ support for ILU. It will also assume that the first executable with an appropriate name is the one you wish to use for compiling programs in that language. By default, it will assume that you wish to include support only for using ONC RPC over TCP/IP. By default, it will assume that you do not wish to provide support for OMG IDL.

imake must be on your path, or in `/usr/bin/X11/', for the build to work properly.

configure Options

The program configure can be invoked with a number of options, to customize the build for your site:

• --with-destdir=PATH -- this should be the name of the directory you would like the files installed into, in the make Install step. The default is `/usr/local/ilu', which may be OK for your system.
• --with-iluhome=PATH -- this should be the name of the directory users will expect ILU to be installed under, the value of ILUHOME. The two options --with-destdir and --with-iluhome are provided separately because a directory may have two different names that are used to access it in different ways. At PARC, for instance, installation directories are often write-protected if named with their ordinary names, and a special name has to be given to enable writing in that directory. If your site does not have this type of restriction, the switches for --with-destdir and --with-iluhome should probably have the same values. Note that the default is `/usr/local/ilu', which may be OK for your system.
• --prefix=PATH -- if specified, this becomes the default for ILUHOME and DESTDIR, if they are not specified explicitly.
• --with-binding-dir=PATH -- a world-writable directory in a file system, for supporting the "simple binding" service described in Chapter 1.
• --enable-sunrpc-protocol -- compiles in support for using ONC RPC across address spaces. (Enabled by default.)
• --enable-courier-protocol -- compiles in support for using XNS Courier RPC across address spaces. (Disabled by default)
• --enable-tcp-transport -- compiles in support for using TCP/IP to transport messages. (Enabled by default.)
• --enable-udp-transport -- compiles in support for using UDP/IP to transport messages. (Disabled by default)
• --enable-omg-idl-support -- builds the support for using OMG IDL with ILU. You will need to have a C++ compiler (CFRONT 3.0 or later) on your path. g++ seems to work fine. (Disabled by default)
• --enable-xview-support -- builds the libraries to interface the XView GUI library to the ILU main loop. (Disabled by default)
• --enable-xt-support -- builds the libraries to interface Xt-based GUI libraries to the ILU main loop. (Disabled by default)
• --enable-tk-support -- builds the libraries to interface Tk-based GUI libraries to the ILU main loop. (Disabled by default)
• --enable-c-support -- enables C support. Use --disable-c-support to turn off the default support for C.
• --enable-cplusplus-support{=PROG} -- enables C++ support. If PROG is specified, treats PROG as the command to use for C++ compilation. Default is to enable C++ support iff the environment variable CXX is defined, in which case CXX should be the compilation command.
• --enable-modula3-support{=M3-COMMAND} -- enables Modula-3 support. If M3-COMMAND is specified, treats M3-COMMAND as the command to use for Modula-3 compilation, otherwise looks for the program m3 on your path, and use the full path name for that program. Default is disabled.
• --enable-lisp-support{=PROG} -- enables Common Lisp support. If PROG is specified, treats PROG as the command to use to invoke Common Lisp. Default is disabled.
• --enable-python-support{=PYTHON-HOME} -- enables Python support. If PYTHON-HOME is specified, treats PYTHON-HOME as the directory in which the Python system is installed. Default is enabled.

Features that are enabled by --enable-FEATURE may also be explicitly disabled with --disable-FEATURE. The particular ANSI C compiler to use may be specified by setting the environment variable CC before running configure.

Building

Now that you have configured the release, do the following to build the system. Note that the capitalization of the arguments to make is important.

1. Set your working directory to ILUSRC:

   % cd ILUSRC
   

2. Build the system with the command:

   % make
   

3. If the build goes well, install the system with the command

   % make Install
   

4. After the installation is complete, you may remove extra files in ILUSRC with the command

   % make Clean
   

   You may wish to use make Clean at any time, to get your system into a consistent state.

5. If you change the configuration files, you should clean the system with the command `make Clean', and redo the installation starting at step 2. If you run into problems that can be fixed without changing the configuration files, you can re-build the system by starting at step 3.

Environment Variables

ILU tools use a number of UNIX environment variables under the covers.

• The variable ILUHOME should be set to point to the value of ILUHOME.
• The variable ILUPATH should be set to a colon-separated list of directories in which the tools look for interface files. A minimal value for ILUPATH is probably .:${ILUHOME}/interfaces.
• Your PATH environment variable should have the directory `ILUHOME/bin' on it.
• Your MANPATH variable should have the directory `ILUHOME/man' on it.
• If you are using Common Lisp, the portable DEFSYSTEM included with ILU uses the value of SYSDCLPATH to find system descriptions. It should be a colon-separated list of directories. A good initial value might be .:${ILUHOME}/lisp. See Appendix A of the reference manual for more details on the portable DEFSYSTEM.
• If you are using Python, the value of the environment variable PYTHONPATH should include the directory in which the ilu library for Python has been installed; that's normally `ILUHOME/lib'.
• The variable ISLDEBUG can optionally be set to any value to enable tracing in the ISL parser.
• The variable ILU_DEBUG can be optionally be set to a colon-separated list of trace values to enable tracing in the ILU runtime kernel. See section Debugging ILU Programs, for more information.

Testing the Build

There are several ways to test the build. The most straightforward is to build and install it somewhere. Set up your environment variables as described above. Then make a scratch directory, which we'll refer to as TESTDIR, and do the following:

% cd TESTDIR
% cp ILUHOME/examples/test1/* .
% ilumkmf
% make client server
ILUHOME/bin/c-stubber  Test1.isl
header file for interface Test1 to ./Test1.h...
common code for interface Test1 to ./Test1-common.c...
code for surrogate stubs of interface Test1 to ./Test1-surrogate.c...
code for true stubs of interface Test1 to ./Test1-true.c...
ILUHOME/bin/c-stubber  Test2.isl
header file for interface Test2 to ./Test2.h...
common code for interface Test2 to ./Test2-common.c...
code for surrogate stubs of interface Test2 to ./Test2-surrogate.c...
code for true stubs of interface Test2 to ./Test2-true.c...
ILUHOME/bin/c-stubber  Test3.isl
header file for interface Test3 to ./Test3.h...
common code for interface Test3 to ./Test3-common.c...
code for surrogate stubs of interface Test3 to ./Test3-surrogate.c...
code for true stubs of interface Test3 to ./Test3-true.c...
rm -f clnt.o
cc -c -g -I. -IILUHOME/include  clnt.c
rm -f Test1-surrogate.o
cc -c -g -I. -IILUHOME/include  Test1-surrogate.c
rm -f Test1-common.o
cc -c -g -I. -IILUHOME/include  Test1-common.c
rm -f Test2-surrogate.o
cc -c -g -I. -IILUHOME/include  Test2-surrogate.c
rm -f Test2-common.o
cc -c -g -I. -IILUHOME/include  Test2-common.c
rm -f Test3-surrogate.o
cc -c -g -I. -IILUHOME/include  Test3-surrogate.c
rm -f Test3-common.o
cc -c -g -I. -IILUHOME/include  Test3-common.c
rm -f client
cc -g -o client clnt.o Test1-surrogate.o Test1-common.o \
  Test2-surrogate.o Test2-common.o Test3-surrogate.o \
  Test3-common.o  ILUHOME/lib/libilu-c.a \
  ILUHOME/lib/libilu.a
rm -f srvr.o
cc -c -g -I. -IILUHOME/include  srvr.c
rm -f Test1-true.o
cc -c -g -I. -IILUHOME/include  Test1-true.c
rm -f Test3-true.o
cc -c -g -I. -IILUHOME/include  Test3-true.c
rm -f server
cc -g -o server srvr.o Test1-common.o Test1-true.o \
  Test2-common.o Test3-common.o Test3-true.o \
  ILUHOME/lib/libilu-c.a ILUHOME/lib/libilu.a
% ./server &
[1] 7079
% exported ilu:Test1-Server/Test1_Initial_Object;ilu%3AiX2w6hjR-...
% ./client
Test1.O1.U-CSS-to-U
u._d=5, u._u.boolean = 1, u._u.O1 = 0x1ffee7c
Test1.O1.f-CSS-to-R0
ro->i=9
Test1.O1.R-ScS-to-F
f=39.700001
Test1.O1.a-RO
Test1.O1.get-O2
got O2, sbh = ilu:Test1-SunRPC-Server/1;ilu%3AaUtts57Ywbp2fxe6+-...
Test1.o2.OO-A0-to-CSS
Test1.O2.R-I-A1-to-I-A0
Test1.O1.get-O3
making O3...
got O3, sbh = ilu:Test1-Server/2;ilu%3An+eRrvAZ8JB9v2qoX7sJGPxdX...
Test1.O3.RS-R-to-R-IS
Test1.O3.O1-U-to-U
u._d=3, u._u.boolean = 0, u._u.O1 = 0xd2b78
Test1.O1.get-O3
got O3, sbh = ilu:Test1-Server/3;ilu%3Ab-mNa9uj0TsJAp7YrlEh0AUfX...
Test3.O.RS-R-to-R-IS
Test3.O.O1-U-to-U(0xd7520, {3})
u._d=3, u._u.boolean = 0, u._u.O1 = 0xd2b78
Test3.O.I-to-Test1U(397)
Test3_O_I_to_Test1U:  u2._d=5, u2._u.boolean = 1, u2._u.O1 = 0x10a88d0
Test1.O1.get-O3
making O4...
got O3, sbh = ilu:Test1-Server/4;ilu%3Ad8sZGQLLpVsJ2PBL5BoIX45qO...
Test1.O4.R_to_R (12345.6789000000) => 1020304.0506070800
doubles:  r1 is 12345.6789000000, r2 is 1020304.0506070800
%

You can proceed to test the various other clients and servers in different languages against each other. See the file `ILUHOME/examples/test1/README' for more information.

Notes on Specific Systems

DEC ALPHA with OSF OS:

From hassan@db.stanford.edu: "Use cc instead of gcc as the C compiler, and make sure to include the `-taso' switch."

From jg@w3.org: "I built [ILU 2.0 alpha on OSF 3.2B] without the `-taso' switch. Is this still needed? c-stubber certainly ran without it this release."

SunOS 4.1.x

Note that the default Sun C compiler is not ANSI C, nor is gcc when installed against the normal Sun header files and `/lib/libc.a'. You will have to use either gcc with the GNU C Library glibc, or the SunPro ANSI C compiler acc, or Lucid Energize lcc, or some other ANSI compiler.

Examples

The following example uses of ILU are provided in the installed tree as subdirectories of `ILUHOME/examples/':

• `tutorial' -- this contains the code for a small ILU tutorial, implemented in both ANSI C and Python. If you are interested in using either of these languages with ILU, we suggest starting with the code in this directory, and one of the files `ILUHOME/doc/tutorial-C.ps' and `ILUHOME/doc/tutorial-Python.ps'. Even if you want to use a different programming language, it's probably worth your while reading one of these tutorials.
• `test1' -- this contains our basic interoperability test program, implemented in a number of languages. If you are interested in working with Common Lisp, Modula-3, or C++, we recommend starting here.
• `multlang' -- an example of using multiple languages (ANSI C and Python) in the same address space, communicating via ILU.
• `blob' -- a contributed Python example.
• `fs' -- an object-oriented file server, written in Common Lisp.
• `foogen' -- an example of using ILU with Modula-3.
• `timeit' -- a crude timing test.
• `test2' -- ANSI C programs to test ASYNCHRONOUS methods and concurrent protocols.
• `changeup' -- a test case to simulate client-server situations where connections are frequently being broken and restored.
• `dialog' -- a simple test program for simulated network failures.

Read the `README' file in each directory first.

Name Servers

No standard "name service" or binding service is provided. We feel that this is an area to be addressed independently, and we may include a name service in future releases of ILU. An experimental simple name service bootstrap interface is available as the simple binding system. See the ANSI C ILU_C_PublishObject, ILU_C_WithdrawObject, and ILU_C_LookupObject, and corresponding routines in the other languages, for more details. This interface is not guaranteed to be present in future releases.

Documentation

ILU documentation is provided in a pre-formatted form, PostScript. The source form of the documentation is called TIM, and is documented in the ILU reference manual. If for some reason you do need to rebuild the documentation, you should have the systems TeX, Perl, ghostscript, dvips, and pbmplus; if you can't find these yourself, please send mail to ilu-core@parc.xerox.com for info on how to find them.

Bug Reporting and Comments

Known Bugs and Gotchas

KNOWN BUGS:

Release 2.0alpha:

1) [C++] The RemoveAll method on sequence objects uses a quadratic algorithm rather than possible linear algorithm.

2) [configuration] Watch out for use of predefined Imake (i.e., cpp) macros in local.defs! Common boobytraps include names of processors, vendors, and operating systems (e.g., sparc, sun), which are used (as isolated tokens according to C rules) in some folks' conventions for naming directories. If you're lucky, you can solve these problems with quoting. A more heavy-duty approach is to #undef the offending macros at the start of local.defs, and re#define them at the end.

3) [kernel] There's no good way to control UDP timeouts. The bad way isn't declared in any header file.

4) [ISL] "TYPE X = OBJECT SUPERTYPES Y ...; TYPE Y = OBJECT SUPERTYPES X ..." crashes the parser (and thus islscan and all the stubbers). Don't do this!

5) [kernel] FoundFD (and TAInvoke) in mainloop.c should unregister I/O hander. There's a patch for this against ILU 1.8 in the 1.8 bugs file.

6) [kernel] Default_Unregister{Input,Output}Source should clear bits. There's a patch for this against ILU 1.8 in the 1.8 bugs file.

7) [MOP] If ilu_AddRegisterersToDefault is used, callers of ilu_Register{Input,Output}Source must be prepared for false callbacks.

8) [C++] iluServer::iluSetMainLoop doesn't pass an ilu_MainLoop with NULLs in the right places in the threaded case.

9) [C++] stubber bugs noted in 1.8 bugs file have not been addressed.

Reporting Bugs

Report bugs (nah! -- couldn't be!) to the Internet address ilu-bugs.parc@xerox.com, or to the XNS address ILU-bugs:PARC:Xerox. Bug reports are more helpful with some information about the activity; please read section Debugging ILU Programs, for more information on how to look at problems. General comments and suggestions can be sent to either ILU@parc.xerox.com or ILU-bugs.

Go to the previous, next section.