Go to the previous, next section.

Installation of ILU

This document describes the installation of version 2.0alpha10 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 Windows NT or 95 System

For information on Windows systems, see the "Using ILU with Microsoft Windows" section of the manual.

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
ftp://ftp.parc.xerox.com/pub/ilu/imake/imake.tar.gz.

ILU normally provides support for a number of languages, currently ANSI C, C++, Java, Python, and Common Lisp (Franz Allegro 4.3, and Harlequin LispWorks), but the 2.0alpha release only contains solid support for ANSI C and Python. There is also minimal C++ support, but it is old and flakey; we're working on a completely new version that will comply with the CORBA 2.0 spec. There is rough (but good) support for Common Lisp in 2.0alpha10. There is rough (but good) support for Java in 2.0alpha10. By `rough', we mean support which is in progress, and will probably change before the official 2.0 release. The Java support for OMG IDL interfaces does not yet completely comply to the CORBA standard mapping.

Unpacking the Distribution

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-2.0alpha10.tar.Z' or `ilu-2.0alpha10.tar.gz' to ILUSRC. Uncompress it if necessary with the uncompress or gunzip program:

% uncompress ilu-2.0alpha10.tar.Z

or

% gunzip ilu-2.0alpha10.tar.gz

Then unpack the tar file:

% tar xf ilu-2.0alpha10.tar

For the Impatient

You can try just unpacking it, and then typing

% make

at the top of the source tree. A minimal configuration using defaults will be built, sufficient for testing. This takes you up through step 2 of the "Building" section below.

Real Configuration

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 java, it will assume that you want to build Java 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.

Configuration Options

The program configure can be invoked with a number of command line options, to customize the build for your site. It actually supports more options than shown here, but these are the only options that will work at this point in the release process.

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 to the full path name of the C compilation command before running configure. Similarly, the particular C++ compiler to use may be specified by setting the environment variable CXX to the full path name of the C++ compilation command to use.

Manual Fixups for Threading

Sadly, our autoconf stuff is not yet fully up to the task of configuring for use of POSIX or Solaris 2 (SunOS 5) threads; you generally have to do a manual step or two, before and/or after running configure.

On some operating systems, linking POSIX threads programs requires a special flag, -lpthread, to appear at the end of the linkage command line. On others, the special flag is -lthreads or -lpthreads. The ILU autoconf system defaults to using -lpthread. You should find out out what the appropriate library for your system is, then, if you've configured with --enable-os-threads, edit `ILUSRC/imake/ilu.defs.new' after running configure but before running make. You should find a definition of the make variable SYSAUX_LIBRARIES that ends with -lpthread; change it to end with -lthreads instead.

On Solaris 2 (SunOS 5), when using the SunPro C and C++ compilers, one of three C preprocessor symbols must be #defined when compiling sources to be included in threaded programs; it's OK to #define these symbols for single-threaded programs too. Of the three, we prefer _REENTRANT because it has no other implications. When configuring to include OS-supplied thread support on Solaris 2, make sure you also explicitly supply a C compilation command, and that it includes -D_REENTRANT to #define this symbol.

On Linux, when using Provenzano's pthreads (POSIX threads) library, you use special scripts provided instead of gcc and g++. Those scripts are normally located at `/usr/local/pthreads/bin/pgcc' and `/usr/local/pthreads/bin/pg++'. Use the facilities described above to configure these scripts as your C and C++ (if you're doing C++) compilers. It's OK to compile even single-threaded programs this way. On our Linux systems, these scripts produce the following warning messages when linking executables:

bfd assertion fail /opt/release/pub/bin/binutils/bfd/elf32-i386.c:624
bfd assertion fail /opt/release/pub/bin/binutils/bfd/elfcode.h:4716

Despite the dire-sounding warnings, the linker seems to produce working executables. Provenzano knows about this, but hasn't tracked it down yet. Sadly, the warning messages trick our autoconf script into thinking this compilation failed, and thus that the requested compilers aren't ANSI-C compliant. To cope with this, we configure to compile with scripts that call the Provenzano scripts and filter out these messages; here's the one for C:

#!/bin/sh -f
/usr/local/pthreads/bin/pgcc $* 2>/tmp/$$-cctmp
ccstatus=$?
fgrep -v "bfd assertion fail /opt/release/pub/bin/binutils/bfd/elf32-i386.c:624" </tmp/$$-cctmp | fgrep -v "bfd assertion fail /opt/release/pub/bin/binutils/bfd/elfcode.h:4716" >&2
rm -f /tmp/$$-cctmp
exit $ccstatus

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. You can then try a simple test with:
    % cd ILUSRC/examples/test1
    % make test
    ../../stubbers/c/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...
    ../../stubbers/c/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...
    ../../stubbers/c/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. -I../../runtime/c -I../../runtime/kernel clnt.c
    rm -f Test1-surrogate.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test1-surrogate.c
    rm -f Test1-common.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test1-common.c
    rm -f Test2-surrogate.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test2-surrogate.c
    rm -f Test2-common.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test2-common.c
    rm -f Test3-surrogate.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test3-surrogate.c
    rm -f Test3-common.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test3-common.c
    rm -f client
    cc  -g -I. -o client  clnt.o Test1-surrogate.o Test1-common.o \
      Test2-surrogate.o Test2-common.o Test3-surrogate.o Test3-common.o \
      ../../runtime/c/libilu-c.a ../../runtime/kernel/libilu.a 
    rm -f srvr.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel srvr.c
    rm -f Test1-true.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test1-true.c
    rm -f Test3-true.o
    cc -c  -g -I. -I../../runtime/c -I../../runtime/kernel Test3-true.c
    rm -f server
    cc  -g -I. -o server  srvr.o Test1-common.o Test1-true.o \
      Test2-common.o Test3-common.o Test3-true.o \
      ../../runtime/c/libilu-c.a ../../runtime/kernel/libilu.a
    ./testserver
    Starting server...
    Running client against server...
    Client run successful.
    Killing server...
    ./testserver: 27469 Terminated
    Exiting with status 0.
    % 
    

  4. If the build goes well, install the system with the command
    % cd ILUSRC
    % make Install
    

  5. 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.

  6. 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. Note three distinct phases when these variables might have significance: (1) when building and installing ILU, (2) when developing an ILU application, and (3) when running an ILU applicaiton.

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

HP/UX

From hassan@db.stanford.edu: "In order to get ILU 2.0a to compile on HP/UX, I had to set the CC environment variable to the following before running configure: setenv CC "/bin/cc -Aa +z -D_HPUX_SOURCE"."

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/':

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 intended to be only sufficient to find the real name service.

Two implementations of this are available, one using an ILU service to store the information, the other using a shared filesystem. They can be selected at configuration time, by specifying either "--with-binding-dir=DIRECTORYNAME", or "--with-binding-service=REALM:HOST:PORT", where REALM may be a user-specified string identifier, that is the name of some conceptual space which the simple binding server serves. These values are compiled into the ILU kernel library, but may be overridden with environment variables at runtime.

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.

Mailing Lists

To be added to, or deleted from, any ILU mailing list, please send mail to ilu-request@parc.xerox.com. Do not send mail to the list itself.

The general ILU discussion mailing list is ilu@parc.xerox.com. People post questions, discuss changes, and help each other out on that list. Another list, used only for announcements of ILU things, and consequently much lower-volume, is ilu-interest@parc.xerox.com. The ilu list receives everything that the ilu-interest list receives; there is no need to be on both lists. Again, send mail to ilu-request@parc.xerox.com to be added to or removed from either of these lists.

Archives of these lists can be found at http://www.findmail.com/listsaver/ilu/?archive/.

Changes

Changes from 2.0alpha9 to 2.0alpha10

Changes from 2.0alpha8 to 2.0alpha9

Changes from 2.0alpha7 to 2.0alpha8

Changes from 1.8 to 2.0alpha

This release contains some major changes, and is NOT compatible "on the wire" with any previous version of ILU. There are also a few API changes. There may be further changes in 2.0beta and 2.0.

Changes from 1.7 to 1.8

Changes from 1.6.4-p9 to 1.7

Bug Reporting and Comments

Known Bugs and Gotchas

KNOWN BUGS:

Release 2.0alpha10:

Release 2.0alpha9:

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.