@c $Id: installation.tim,v 1.92 1996/07/17 19:04:28 janssen Exp $
@setfilename ilu-installation.info
@settitle ILU Installation Instructions, release RELEASE_NUMBER
@ifclear largerdoc
@titlepage
@title ILU Installation Instructions, release RELEASE_NUMBER
@author Bill Janssen @code{<janssen@@parc.xerox.com>}
@sp
(typeset @today{})
@sp
Copyright @copyright{} 1994, 1995 Xerox Corporation@*
All Rights Reserved.
@end titlepage
@end ifclear

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

@emph{If you succeed in installing @system{ILU} on a particular platform,
we'd appreciate it if you could send a note to @code{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 @system{ILU} you used.  We're accumulating
a list of operating systems and compilers that work with @system{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.}

@section Installing on a UNIX System

@subsection Prerequisites

You will need an @language{ANSI C} compiler to build and install
@system{ILU}, along with an @language{ANSI C}-compliant @file{libc.a}.
Note that @system{GNU} @program{gcc} doesn't always work as an @language{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:

@codeexample
#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;
@}
@end codeexample

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

@system{ILU} normally provides support for a number of languages, currently @language{ANSI C}, @language{C++},
@language{Modula-3}, @language{Python}, and @language{Common Lisp} (Franz Allegro 4.2, and Harlequin LispWorks), but the 2.0alpha release only contains support for @language{ANSI C} and @language{Python}.  There is also minimal @language{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.
@itemize @bullet
@item
If you wish to build the support for @language{ANSI C}, you will need a @language{C}
compiler, and an @language{ANSI C}-compliant libc.  But you already need that to build @system{ILU}.
@item
The @language{C++} support included in this version of @system{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 @system{ILU}.  We do not recommend serious use of the current
@language{C++} support, but it is included for use in testing other parts of the system.
If you wish to build the support for @language{C++}, you will need a @language{C++}
compiler that conforms to at least version 2.0 of the C++ specification.  @system{ILU} does not use
either @language{C++} templates or exceptions, as these are too spottily implemented
to be relied on.  The @system{GNU} @language{C}/@language{C++} compiler @program{g++} seems
to work well with @system{ILU}.  It has also been tested with Lucid's Energize @program{lcc} compiler,
CenterLine's @program{CC} compiler, and Sun's @program{CC} compiler.
@item
If you wish to build support for @language{Modula-3}, you will need to wait for the 2.0beta
release.
@item
If you wish to build the support for @language{Common Lisp}, you will need to wait for
the 2.0beta release.
@item
If you with to build support for @language{Python}, you will need the @language{Python} 1.2 (or later)
release, available via FTP from @file{ftp://ftp.cwi.nl/pub/python/}.  When installing @language{Python} on your system,
be sure to do a "make inclinstall", so that the include files are installed for @system{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.
@end itemize

@subsection Unpacking the Distribution

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

Copy the compressed tar file @file{ilu-RELEASE_NUMBER.tar.Z} or @file{ilu-RELEASE_NUMBER.tar.gz} to
@metavar{ILUSRC}.  Uncompress it if necessary with
the @program{uncompress} or @program{gunzip} program:

@transcript
% @userinput{uncompress ilu-RELEASE_NUMBER.tar.Z}
@end transcript

or

@transcript
% @userinput{gunzip ilu-RELEASE_NUMBER.tar.gz}
@end transcript

Then unpack the tar file:

@transcript
% @userinput{tar xf ilu-RELEASE_NUMBER.tar}
@end transcript

@subsection For the Impatient

You can try just unpacking it, and then typing

@transcript
% @userinput{make}
@end transcript

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.

@subsection Real Configuration

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

@transcript
% @userinput{./configure}
@end transcript

@noindent
at the top of the source tree.

What will happen is that @program{@metavar{ILUSRC}/imake/configure} will go out and look along
the value of your PATH environment variable for various executable
programs.  If it finds @program{cc}, it will assume that you want to build
@language{ANSI C} support for @system{ILU}.  If it finds @program{m3}, it will assume
that you want to build @language{Modula-3} support for @system{ILU}.  If it
finds @program{cl} or @program{franz}, it will assume that you want to build
@language{Lisp} support for @system{ILU}.  If it finds @program{python}, it will
assume that you want to build @language{Python} support for
@system{ILU}.  If it finds @program{CC} or @program{cxx} or @program{c++}, it will assume that you want to build
@language{C++} support for @system{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 @protocol{ONC RPC} over @transport{TCP/IP}.
By default, it will assume that you do not wish to provide support for @language{OMG IDL}.

@program{imake} must be on your path, or in @file{/usr/bin/X11/}, for the build to work properly.

@subsubsection @program{configure} Options

The program @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.

@itemize @bullet
@item
@var{--with-destdir=PATH} -- this should be the name of the directory you would like
the files installed into, in the @userinput{make Install} step.  The default
is @file{/usr/local/ilu}, which may be OK for your system.
@item
@var{--with-iluhome=PATH} -- this should be the name of the directory
users will expect @system{ILU} to be installed under, the value of @metavar{ILUHOME}.  The two options
@var{--with-destdir} and @var{--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 @var{--with-destdir} and @var{--with-iluhome}
should probably have the same values.  Note that the default is @file{/usr/local/ilu}, which
may be OK for your system.
@item
@var{--prefix=PATH} -- if specified, this becomes the default for @metavar{ILUHOME} and @metavar{DESTDIR},
if they are not specified explicitly.
@item
@var{--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.
@item
@var{--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 @metavar{REALM} will be available
on port @metavar{PORT} of host @metavar{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.
@item
@var{--enable-os-threads[=TYPE]} -- compiles in support for using either "solaris2" or "posix" threads with the @language{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.
@item
@var{--enable-sunrpc-protocol} -- compiles in support for using @protocol{ONC RPC} across address spaces.  (Enabled by default.)
@item
@var{--enable-courier-protocol} -- compiles in support for using @protocol{XNS Courier RPC} across address spaces.  (Disabled by default)
@item
@var{--enable-corba-iiop} -- compiles in support for using the @system{CORBA} @protocol{Internet Inter-Orb Protocol} across address spaces.  (Disabled by default)
@item
@var{--enable-http-protocol} -- compiles in support for using the @system{World Wide Web} @protocol{HTTP 1.0} between address spaces.  (Disabled by default)
@item
@var{--enable-tcp-transport} -- compiles in support for using @transport{TCP/IP} to transport messages.  (Enabled by default.)
@item
@var{--enable-udp-transport} -- compiles in support for using @transport{UDP/IP} to transport messages.  (Disabled by default, and we think it's currently broken)
@item
@var{--enable-omg-idl-support} -- builds the support for using @language{OMG IDL} with @system{ILU}.  You will need to have a @language{C++} compiler (CFRONT 3.0 or later) on your path.  @program{g++} seems to work fine.  (Disabled by default)
@item
@var{--enable-xview-support} -- builds the libraries to interface the @system{XView} GUI library to the @system{ILU} main loop.  (Disabled by default)
@item
@var{--enable-xt-support} -- builds the libraries to interface @system{Xt}-based GUI libraries to the @system{ILU} main loop.  (Disabled by default)
@item
@var{--enable-tk-support} -- builds the libraries to interface @system{Tk}-based GUI libraries to the @system{ILU} main loop.  (Disabled by default)
@item
@var{--disable-c-support} -- disables @language{C} support.  (Enabled by default.)
@item
@var{--enable-cplusplus-support@{=@metavar{PROG}@}} -- enables @language{C++} support.  If @metavar{PROG} is specified, treats @metavar{PROG} as the command to use for @language{C++} compilation; @metavar{PROG} must be the full path name.  Default is to enable
@language{C++} support iff the environment variable @metavar{CXX} is defined,
in which case @metavar{CXX} should be the full path name of the compilation command.
@item
@var{--enable-python-support@{=@metavar{PYTHON-HOME}@}} -- enables @language{Python} support.  If @metavar{PYTHON-HOME} is specified, treats @metavar{PYTHON-HOME} as the directory in which the @language{Python} system is installed.  Default is enabled.
@end itemize

Features that are enabled by @var{--enable-FEATURE} may also be explicitly disabled with @var{--disable-FEATURE}.

The particular @language{ANSI C} compiler to use may be specified by setting the environment variable @var{CC} to the full path name of the C compilation command before running @program{configure}.  Similarly, the particular C++ compiler to use may be specified by setting the environment variable @var{CXX} to the full path name of the C++ compilation command to use.

@subsubsection Manual Fixups for Threading

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

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

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

On @system{Linux}, when using Provenzano's pthreads (POSIX threads) library, you use special scripts provided instead of @program{gcc} and @program{g++}.  Those scripts are normally located at @file{/usr/local/pthreads/bin/pgcc} and @file{/usr/local/pthreads/bin/pg++}.  Use the facilities described above to configure these scripts as your @language{C} and @language{C++} (if you're doing @language{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:

@transcript
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
@end transcript

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 @system{autoconf} script into thinking this compilation failed, and thus that the requested compilers aren't @language{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 @language{C}:

@transcript
#!/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
@end transcript


@subsection Building

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

@enumerate
@item
Set your working directory to @metavar{ILUSRC}:
@transcript
% @userinput{cd @metavar{ILUSRC}}
@end transcript

@item
Build the system with the command:
@transcript
% @userinput{make}
@end transcript

@item
You can then try a simple test with:
@transcript
% @userinput{cd @metavar{ILUSRC}/examples/test1}
% @userinput{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.
% 
@end transcript

@item
If the build goes well, install the system with the command
@transcript
% @userinput{cd @metavar{ILUSRC}}
% @userinput{make Install}
@end transcript

@item
After the installation is complete, you may remove extra files in @metavar{ILUSRC}
with the command
@transcript
% @userinput{make Clean}
@end transcript
You may wish to use @command{make Clean} at any time, to get your
system into a consistent state.

@item
If you change the configuration files, you should clean the system with the command
`@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.
@end enumerate

@subsection Environment Variables

@system{ILU} tools use a number of @system{UNIX} environment variables under the covers.  Note three distinct phases when these variables might have significance: (1) when building and installing @system{ILU}, (2) when developing an @system{ILU} application, and (3) when running an @system{ILU} applicaiton.

@itemize @bullet
@item
The variable @var{ILUHOME} should be set to point to the value of @metavar{ILUHOME}.  When does this matter??
@item
The variable @var{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 @file{.:@metavar{ILUHOME}/interfaces} is used.
@item
You may want your @var{PATH}
environment variable to include the directory @file{@metavar{ILUHOME}/bin} during phase (2).  This makes it possible to invoke @system{ILU} development tools (e.g., stubbers, @language{TIM} tools) by short names.  Most of the @system{ILU} development tools can be invoked by their full pathnames, without @file{@metavar{ILUHOME}/bin} being on your @var{PATH}; some of the @language{TIM} tools require @file{@metavar{ILUHOME}/bin} to be on your @var{PATH}.
@item
After phase (1), your @var{MANPATH} variable can have the directory @file{@metavar{ILUHOME}/man} on it.
@item
If you are using @language{Common Lisp}, the portable DEFSYSTEM included with
@system{ILU} uses the value of @var{SYSDCLPATH} to find system descriptions.  It should
be a colon-separated list of directories.  A good initial value might be
@code{.:$@{ILUHOME@}/lisp}.  See Appendix A of the reference manual for more details on the portable
DEFSYSTEM.
@item
If you are using @language{Python}, the value of the environment variable @var{PYTHONPATH}
should include the directory in which the @module{ilu} library for
@language{Python} has been installed;
that's normally @file{@metavar{ILUHOME}/lib}.  When is this significant???
@item
During phase (2), the variable @var{ISLDEBUG} can optionally be set to any value to enable tracing
in the @language{ISL} parser.
@item
During phase (3), the variable @var{ILU_DEBUG} can be optionally be set to a colon-separated list of
trace values to enable tracing in the @system{ILU} runtime kernel.  @xref{Debugging ILU Programs}, for more information.
@item
If you are using the ``shared filesystem'' approach to @system{ILU} simple binding, the default directory for
registration files may be overridden at run-time by setting the environment variable @var{ILU_BINDING_DIRECTORY}
to the path of a different directory.
@item
If you are using the ``@system{ILU} service'' approach to @system{ILU} simple binding, the default values for
the @metavar{REALM-NAME}, @metavar{HOST}, and @metavar{PORT} may be overridden by setting the value of the
environment variable @var{ILU_BINDING_SERVICE} to a string of the form @code{"@metavar{realm-name}:@metavar{host}:@metavar{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 @code{"::2034"}, which would mean to use the default values for @system{REALM-NAME} and @system{HOST}, and the value of @code{2034} for the port.
@end itemize

@subsection 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 @metavar{TESTDIR}, and
do the following:

@transcript
% @userinput{cd @metavar{TESTDIR}}
% @userinput{cp @metavar{ILUHOME}/examples/test1/* .}
% @userinput{ilumkmf}
% @userinput{make client server}
@metavar{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...
@metavar{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...
@metavar{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. -I@metavar{ILUHOME}/include  clnt.c
rm -f Test1-surrogate.o
cc -c -g -I. -I@metavar{ILUHOME}/include  Test1-surrogate.c
rm -f Test1-common.o
cc -c -g -I. -I@metavar{ILUHOME}/include  Test1-common.c
rm -f Test2-surrogate.o
cc -c -g -I. -I@metavar{ILUHOME}/include  Test2-surrogate.c
rm -f Test2-common.o
cc -c -g -I. -I@metavar{ILUHOME}/include  Test2-common.c
rm -f Test3-surrogate.o
cc -c -g -I. -I@metavar{ILUHOME}/include  Test3-surrogate.c
rm -f Test3-common.o
cc -c -g -I. -I@metavar{ILUHOME}/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  @metavar{ILUHOME}/lib/libilu-c.a \
  @metavar{ILUHOME}/lib/libilu.a
rm -f srvr.o
cc -c -g -I. -I@metavar{ILUHOME}/include  srvr.c
rm -f Test1-true.o
cc -c -g -I. -I@metavar{ILUHOME}/include  Test1-true.c
rm -f Test3-true.o
cc -c -g -I. -I@metavar{ILUHOME}/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 \
  @metavar{ILUHOME}/lib/libilu-c.a @metavar{ILUHOME}/lib/libilu.a
% @userinput{./server &}
[1] 7079
% exported ilu:Test1-Server/Test1_Initial_Object;ilu%3AiX2w6hjR-...
% @userinput{./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
%
@end transcript

@noindent
You can proceed to test the various other clients and servers in different languages against
each other.  See the file @file{@metavar{ILUHOME}/examples/test1/README} for more information.

@subsection Notes on Specific Systems

@subsubsection HP/UX

From @code{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:  @code{setenv CC "/bin/cc -Aa +z -D_HPUX_SOURCE"}.''

@subsubsection DEC ALPHA with OSF OS

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

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

@subsubsection SunOS 4.1.x

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

@section Examples

The following example uses of @ilu are provided in the installed
tree as subdirectories of @file{@metavar{ILUHOME}/examples/}:

@itemize @bullet
@item @file{tutorial} -- this contains the code for a small @ilu tutorial,
implemented in both @language{ANSI C} and @language{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 @file{@metavar{ILUHOME}/doc/tutorial-C.ps} and
@file{@metavar{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.
@item @file{test1} -- this contains our basic interoperability test program,
implemented in a number of languages.
If you are interested in working with @language{Common Lisp}, @language{Modula-3}, or @language{C++},
we recommend starting here.
@item @file{multlang} -- an example of using
multiple languages (@language{ANSI C} and @language{Python}) in the same address space, communicating via @ilu.
@item @file{blob} -- a contributed @language{Python} example that uses @system{Tk}.
@item @file{timeit} -- a crude timing test.
@end itemize

@noindent
Read the @file{README} file in each directory first.

@section 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 @system{ILU}.
An experimental simple name service bootstrap interface is available as the @dfn{simple binding system}.
See the @language{ANSI C} @C{ILU_C_PublishObject}, @C{ILU_C_WithdrawObject}, and @C{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 @system{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 @system{ILU} kernel library,
but may be overridden with environment variables at runtime.

@section Documentation

@system{ILU} documentation is provided in a pre-formatted form, @language{PostScript}.  The source form
of the documentation is called @language{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{}, @language{Perl}, @system{ghostscript}, @program{dvips},
and @system{pbmplus}; if you can't find these yourself,
please send mail to @code{ilu-core@@parc.xerox.com} for info on how to find them.

@section Mailing Lists

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

The general ILU discussion mailing list is @code{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 @code{ilu-interest@@parc.xerox.com}.  The @code{ilu} list receives everything that the @code{ilu-interest} list receives; there is no need to be on both lists.  Again, send mail to @code{ilu-request@@parc.xerox.com} to be added to or removed from either of these lists.

Archives of these lists can be found at @url{http://www-diglib.stanford.edu/ilu/"}.

@section Changes

@subsection Changes from 2.0alpha7 to 2.0alpha8

@itemize @bullet

@item @emph{HTTP protocol added.}  This allows you to use the standard World Wide Web @protocol{HTTP}, version 1.0, between address spaces.  In some sense, this makes @system{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.

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

@item @emph{@system{ILU} Simple Binding via an @system{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.

@item @emph{@program{ilusbls}}  A program, @program{ilusbls}, that will list the objects known to the simple binding service, is provided.  @program{ilusbls} will work with either the shared files simple binding or the @system{ILU} service simple binding.

@item @emph{Identities exported via a meta-object protocol.}  Application-specific identity types may now be registered with the @system{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 @file{runtime/kernel/iluxport.h} for more information on @C{ilu_IdentityInfo}.

@item @emph{Python threading supported.}  If @system{ILU} is configured with @var{--enable-os-threads}, and your @language{Python} installation has been built with thread support, thread support will also be available in the @language{Python} @system{ILU} runtime.  A new @language{Python} function, @Python{ilu.ThreadedOperation()}, has been added to enable use of threads.

@item @emph{ILU/Python support for Windows NT.}

@item @emph{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 @system{ONC RPC} and @system{XNS Courier} wire formats; the program numbers used have been changed to reflect this.

@item @emph{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 @system{ILU} 2.0alpha7 will not be compatible with those of 2.0alpha8.

@item Various fixes, to all the problems reported in @url{ftp://ftp.parc.xerox.com/pub/ilu/2.0/2.0alpha7-patches.html}, and more.

@end itemize

@subsection 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.

@itemize @bullet

@item We now use GNU autoconf (and still use imake).

@item 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).

@item 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).

@item 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!

@item ILU string binding handles become IETF URLs.

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

@item 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.

@end itemize

@subsection Changes from 1.7 to 1.8

@itemize @bullet

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

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

@item 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.

@item 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.

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

@item 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.

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

@item 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.

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

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

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

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

@end itemize

@subsection Changes from 1.6.4-p9 to 1.7

@itemize @bullet

@item 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.

@item 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.

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

@item Support for the Python programming language has been added.

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

@item 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.

@item 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.

@item Network GC now works.

@item Numerous bugs have been fixed.

@end itemize

@section Bug Reporting and Comments

@subsection Known Bugs and Gotchas

KNOWN BUGS:

Release 2.0alpha8:

@itemize @bullet

@item @i{[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.

@item @i{[kernel]}  We currently have no way to tell when it is safe to
@C{free()} or re-use a connection data structure, so we leak connection
data structures.

@item @i{[kernel]}  When marshalling large strings or byte sequences, copies
occur which shouldn't.

@item @i{[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.

@item @i{[kernel]} There's no good way to control UDP timeouts.  The bad way
isn't declared in any header file.

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

@item @i{[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!

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

@item @i{[C++]}  The current @language{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 @system{ILU}.  We do not recommend serious use of the current
@language{C++} support, but it is included for use in testing other parts of the system.

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

@end itemize

@subsection Reporting Bugs

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