   This document describes the installation of version 2.0alpha8 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

   `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 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.
   * 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.

   * The C++ support included in this version of ILU is old and buggy.
     There are known leaks in the generated stubs, and in the runtime
     itself.  It is being completely re-worked for version 2.0 of ILU.
     We do not recommend serious use of the current C++ support, but it
     is included for use in testing other parts of the system.  If you
     wish to build the support for C++, you will need a C++ compiler
     that conforms to at least 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.2 (or later) release, available via FTP from
     `ftp://ftp.cwi.nl/pub/python/'.  When installing Python on your
     system, be sure to do a "make inclinstall", so that the include
     files are installed for ILU's use.  It's also advisable to do
     "make libainstall", if you wish to try the `multiple languages in
     the same address space' example.

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

     % uncompress ilu-2.0alpha8.tar.Z

   or

     % gunzip ilu-2.0alpha8.tar.gz

   Then unpack the tar file:

     % tar xf ilu-2.0alpha8.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 `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.  It actually supports more options
than shown here, but these are the only options that will work at this
point in the release process.

   * `--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 shared
     file system, for supporting the "simple binding" service described
     in Chapter 1.  This option and the use of a binding service (see
     next item) are mutually exclusive.

   * `--with-binding-server=REALM:HOST:PORT' - an alternative to using
     the shared file system for simple binding, this says that a
     binding registration server for the binding realm called REALM
     will be available on port PORT of host HOST.  The binding server
     will be built and installed as part of the build process, but
     still has to be started manually.  This option and the use of a
     binding directory are mutually exclusive.

   * `--enable-os-threads[=TYPE]' - compiles in support for using
     either "solaris2" or "posix" threads with the C support.  If the
     TYPE isn't specified, it will attempt to guess the right default.
     The default is to enable thread support for platforms where the
     configure script knows thread support exists (currently only
     Solaris 2 (Solaris 2 threads) and OSF 1.3 (POSIX threads).  See
     the following section on "Manual Fixups for Threading", as well.

   * `--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-corba-iiop' - compiles in support for using the CORBA
     `Internet Inter-Orb Protocol' across address spaces.  (Disabled by
     default)

   * `--enable-http-protocol' - compiles in support for using the World
     Wide Web `HTTP 1.0' between 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, and we think it's
     currently broken)

   * `--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)

   * `--disable-c-support' - disables C support.  (Enabled by default.)

   * `--enable-cplusplus-support{=PROG}' - enables C++ support.  If
     PROG is specified, treats PROG as the command to use for C++
     compilation; PROG must be the full path name.  Default is to enable
     C++ support iff the environment variable CXX is defined, in which
     case CXX should be the full path name of the compilation command.

   * `--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' 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 `#define'd 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.

   * The variable `ILUHOME' should be set to point to the value of
     ILUHOME.  When does this matter??

   * The variable `ILUPATH' is significant to the stubbers and other
     interface-processing tools, normally used in phase (2).  If this
     variable is defined, it is a colon-separated list of directories
     that are searched, in addition to those specified on the relevant
     tool's command line, for interface files.  If this variable is not
     defined, the value `.:ILUHOME/interfaces' is used.

   * You may want your `PATH' environment variable to include the
     directory `ILUHOME/bin' during phase (2).  This makes it possible
     to invoke ILU development tools (e.g., stubbers, TIM tools) by
     short names.  Most of the ILU development tools can be invoked by
     their full pathnames, without `ILUHOME/bin' being on your `PATH';
     some of the TIM tools require `ILUHOME/bin' to be on your `PATH'.

   * After phase (1), your `MANPATH' variable can 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'.  When is this significant???

   * During phase (2), the variable `ISLDEBUG' can optionally be set to
     any value to enable tracing in the ISL parser.

   * During phase (3), 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.  *Note Debugging ILU Programs::, for more
     information.

   * If you are using the "shared filesystem" approach to ILU simple
     binding, the default directory for registration files may be
     overridden at run-time by setting the environment variable
     `ILU_BINDING_DIRECTORY' to the path of a different directory.

   * If you are using the "ILU service" approach to ILU simple binding,
     the default values for the REALM-NAME, HOST, and PORT may be
     overridden by setting the value of the environment variable
     `ILU_BINDING_SERVICE' to a string of the form
     `"REALM-NAME:HOST:PORT"'.  Any of the three fields may be empty,
     so you could override just the port, for example, by using a value
     of the form `"::2034"', which would mean to use the default values
     for REALM-NAME and HOST, and the value of `2034' for the port.

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

   * `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 that uses Tk.

   * `timeit' - a crude timing test.

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-diglib.stanford.edu/ilu/"'.

Changes
=======

Changes from 2.0alpha7 to 2.0alpha8
-----------------------------------

   * *HTTP protocol added.*  This allows you to use the standard World
     Wide Web `HTTP', version 1.0, between address spaces.  In some
     sense, this makes ILU programs Web servers and clients, though
     only in a very limited sense.  See the `Protocols and Transports'
     chapter of the user manual for more information.

   * *OS threading added.*  We've added support for use of the
     operating system's threads, if available, with the languages C,
     C++, and Python.  The threading systems supported are POSIX
     threads, Solaris 2 threads, and Windows/NT threads.  See
     `examples/test1/srvr.c' for an example of using threads.

   * *ILU Simple Binding via an ILU service.*  You can now choose to
     `simple binding' via either a shared file system or via an ILU
     service.  See the chapter on `ILU Concepts' for more information.

   * *`ilusbls'*  A program, `ilusbls', that will list the objects
     known to the simple binding service, is provided.  `ilusbls' will
     work with either the shared files simple binding or the ILU
     service simple binding.

   * *Identities exported via a meta-object protocol.*
     Application-specific identity types may now be registered with the
     ILU kernel, and procedures to `pickle' and `unpickle' them are
     supported.  Application-specific protocols and transports have
     access to these identity objects, and can use them for various
     security, accounting, and authorization strategies.  See
     `runtime/kernel/iluxport.h' for more information on
     `ilu_IdentityInfo'.

   * *Python threading supported.*  If ILU is configured with
     `--enable-os-threads', and your Python installation has been built
     with thread support, thread support will also be available in the
     Python ILU runtime.  A new Python function,
     `ilu.ThreadedOperation()', has been added to enable use of threads.

   * *ILU/Python support for Windows NT.*

   * *Change in default marshalling of discriminant references.*  We
     switched to using a more efficient representation for server IDs
     when marshalling the discriminant of a call on the wire.  This
     changes our ONC RPC and XNS Courier wire formats; the program
     numbers used have been changed to reflect this.

   * *Change in algorithm to compute type UIDs.*  We switched to a much
     more efficient algorithm for computing the structural fingerprint
     of a type.  As a result, all stubbed files should be re-stubbed;
     the type IDs from ILU 2.0alpha7 will not be compatible with those
     of 2.0alpha8.

   * Various fixes, to all the problems reported in
     `ftp://ftp.parc.xerox.com/pub/ilu/2.0/2.0alpha7-patches.html', and
     more.

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.

   * We now use GNU autoconf (and still use imake).

   * Support for C and C++ use on Windows 95 and Windows NT (Windows 3.1
     coming soon), thanks to Dan Larner.  Windows binaries are available
     (as well as source code).

   * Thanks to Bridget Spitznagel, we now have support for
     cross-language calls within the same address space.  Because we're
     not a compiler vendor, and can't keep up with all the compiler
     vendors in the world (not to mention all the combinations of
     them), we don't solve your problem of getting multiple language
     runtimes to co-exist.  But where you *have* solved that problem
     (perhaps because you've got an easy instance, such as C and XXX),
     you can now just call through an ILU interface -- rather than
     having to write messy "foreign function" interfaces from one
     language to another.  Each part of your program looks mono-lingual
     and normal, and we provide the control-flow and data-conversion
     glue to put them together.  Data conversion is currently done by
     serializing and de-serializing to/from a normalized form in a
     memory buffer; we plan to investigate more direct methods (but not
     necessarily for release 2.0).

   * Our "transport" abstraction has been re-organized.  Among other
     things, this makes it (relatively) easy to introduce "filters" at
     the transport level.  Of course, ILU remains open and extensible
     in this regard.  Want to add a compression filter?  Go ahead!

   * ILU string binding handles become IETF URLs.

   * We've made it possible for a calling application to interrupt a
     call in progress.

   * The documentation (and of course, TIM) has diagrams and URLs!

     8) Generalized cleanup and bug fixing.  This includes more
     attention to making it practical for others to add transport and
     protocol meta-objects.  This also includes a more rigorous
     treatment of exceptions in the kernel and runtimes, with a
     taxonomy of exceptions aligned with CORBA's.  It also includes
     fixes that change the type ID's and protocol mappings, which
     caused us to bump the major version number.  All ONC RPC and
     Courier program numbers, and ISO object IDs are now official.  The
     Courier type-ID-to-program-number mapping registry has been
     eliminated.

Changes from 1.7 to 1.8
-----------------------

   * A kernel memory leak caused by having many clients connect to,
     then drop, a server was fixed.

   * File descriptors are now removed from the event loop registry when
     a connection is closed, which fixes some errors in various
     runtimes.

   * The kernel routines ilu_ConsiderSBH() and ilu_ReLookupObject() are
     now provided to change the binding of a surrogate kernel server.
     This allows a client to track changes caused when a server goes
     down and is re-started with different contact info.  This should
     also handle the relocation requirement of CORBA's IIOP.  They have
     not been fully tied into the language runtimes yet.  Some language
     runtime code may still improperly keep a cache of an earlier SBH.

   * The Common Lisp garbage collector is now tied in to the ILU network
     GC scheme, so that client interest in collectible true objects is
     communicated and used properly between Lisp clients and servers.
     Collectible true objects are now GC'ed.

   * A new appendix to the ILU manual documents the process of adding
     ILU support for a different variety of Common Lisp.

   * Various fixes to the Python support have been made to fix various
     bugs, and to allow unregistration of Tk event handlers when
     connections are closed.  Python true objects must still be manually
     held onto by the server.

   * References into freed data structures have been fixed in the C and
     C++ runtime, thanks to Purify.

   * An authentication framework has been added, but no protocols
     currently pass any identity information except for the Sun RPC
     protocol's default authentication of "AUTH_UNIX".  This identity is
     now available in C true method code, but the access method is not
     yet documented, as it will surely change.

   * An obscure bug in the Lisp generic process code, responsible for
     causing an occasional "Bad Process-Lock" message, has been fixed.

   * The XView X toolkit code in ILUSRC/etc/xview/ has been
     successfully used.

   * Memory leaks in C true stubs have been fixed, and C true stubs now
     report unexpected exceptions properly.

   * Fixes from hassan@db.stanford.edu for the DEC Alpha system with
     OSF/1 have been incorporated.

Changes from 1.6.4-p9 to 1.7
----------------------------

   * The way of associating a Sun RPC (program number, version) tuple
     with an object type has changed.  In release 1.6.4, the (program
     number, version) was assigned either manually or automatically,
     and a file maintained a list of (type ID, program #, version)
     tuples.  Each client and server consulted this file when mapping
     between Sun RPC program #'s and ILU type ID's.  This led to a
     number of problems.  This scheme has been changed in release 1.7
     to a scheme in which the Sun RPC program # is always the value
     0x31000400, and the (32-bit) Sun RPC version is computed from the
     ILU type ID, using the CRC-32 hash algorith.  Thus the version
     number is the CRC-32 of the ILU type ID.  This has been tested for
     collisions, and they have been found to be extremely rare - much
     rarer than collisions would have been under the ILU 1.6.4 scheme.

     This means that if you wish to use ILU 1.6.4 clients or servers
     with ILU 1.7, you should edit the 1.6.4 SunRPCRegistry file to use
     the 1.7 program number and version for each particular object type.

   * The C runtime now offers an interface to threads, so that C servers
     can handle requests in different threads.  This has been tested
     with the PPCR implementation of POSIX threads.

   * Untested pseudo-threads libraries for the Xt and XView X toolkits
     are provided, under ILUSRC/etc/{Xt,xview}/.

   * Support for the Python programming language has been added.

   * All languages now support IN, OUT, and INOUT method parameters.

   * Support for CORBA NIL object references has been added, via the new
     OPTIONAL keyword on object types.  All object types defined with
     OMG IDL will be tagged automatically with OPTIONAL; object types
     defined with ILU ISL have the option of being OPTIONAL.  Note that
     this keyword is different from the ISL OPTIONAL type constructor.
     The use of this keyword in ISL is deprecated in favor of the
     OPTIONAL type constructor.

     This also means that the ILU on-the-wire mapping for objects has
     been changed (slightly) to allow for NIL object references.
     Applications that do not use NIL objects will not encounter this
     change.

   * The usage of the SINGLETON keyword on object types has changed.  It
     now takes a string argument which defines the particular "pinfo"
     and "tinfo" to be used with the object type.

   * Network GC now works.

   * Numerous bugs have been fixed.

Bug Reporting and Comments
==========================

Known Bugs and Gotchas
----------------------

   KNOWN BUGS:

   Release 2.0alpha8:

   * [configuration] Since our Makefiles are constructed via imake from
     Imakefiles, which involves running the C preprocessor, watch out
     for use of predefined C preprocessor symbols in pathnames!  Common
     boobytraps include names of processors, vendors, and operating
     systems (e.g., "sparc", "sun", "hpux"), 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 imake/ilu.defs.new, and
     re#define them at the end.

   * [kernel]  We currently have no way to tell when it is safe to
     `free()' or re-use a connection data structure, so we leak
     connection data structures.

   * [kernel]  When marshalling large strings or byte sequences, copies
     occur which shouldn't.

   * [kernel]  UDP seems to currently have several bugs which render it
     more than usually unreliable.  We don't recommend trying to use it
     till we fix it.

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

   * [Windows]  The ILU service simple binding has not yet been ported
     to Windows, so only the shared-file simple binding will work with
     Windows.

   * [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!

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

   * [C++]  The current C++ support is old and buggy.  There are known
     leaks in the generated stubs, and in the runtime itself.  It is
     being completely re-worked for version 2.0 of ILU.  We do not
     recommend serious use of the current C++ support, but it is
     included for use in testing other parts of the system.

   * [Security] Not released yet!  We're updating our GSS implementation
     to the latest version of the spec, so we decided to hold it back
     for this release.

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 *Note 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'.

