INSTALLATION NOTES FOR THE ADAPTIVE COMMUNICATION ENVIRONMENT (ACE)

---------------------------------------------------------- 
Please make sure you read the ./FAQ before installing ACE!  In
addition, please consult the ChangeLog file to see whether any recent
changes to the release will affect your code.
----------------------------------------------------------

INSTALLATION PROCESS

The installation process for ACE is relatively simple (and is getting
easier over time).  Here's what you need to do:

        * Install GNU make 3.65 or greater on your system (available
          via anonymous ftp from prep.ai.mit.edu in the pub/gnu
          directory).

        * Add an environment variable called WRAPPER_ROOT that
          contains the name of the root of the directory where you
          keep the ACE wrapper source tree.  For example, in my .login
          file I have the following entry:
          
          setenv WRAPPER_ROOT /home/cs/faculty/schmidt/ACE_wrappers
          
          The ACE recursive Makefile system needs this information.
          
        * Edit the $WRAPPER_ROOT/ace/OS.h file to update
          things like default hostname and port numbers you'd like the
          programs in the $WRAPPER_ROOT/{apps,tests} directories to
          use by default.

        * Set the $WRAPPER_ROOT/ace/config.h file to point to the
          appropriate platform/compiler-specific header configurations
          (such as config-sunos5-sunc++-4.x.h).  This file contains
          the #defines that are used throughout ACE to indicate which
          features your system supports (see the
          $WRAPPER_ROOT/ace/sysincludes.h file for many examples of
          how the ACE build configuration is affected by these macro
          settings).

          There are config files for most versions of UNIX.  If there
          isn't a version of this file that matches your
          platform/compiler, you'll need to make one.  Please send me
          email if you get it working so I can add it to the master
          ACE release.

        * Set the $WRAPPER_ROOT/include/makeinclude/platform_macros.GNU 
	  file to point to the appropriate platform/compiler-specific
          Makefile configurations (e.g., platform_sunos5_sunc++.GNU).
          This file contains the compiler and Makefile directives that
          are platform/compiler-specific
          
        * Note that since ACE builds shared libraries, you'll need to
          set LD_LIBRARY_PATH to whereever you put the binary version
          of the libraries.  For example, you probably want to do
          somethink like the following
          
          % setenv LD_LIBRARY_PATH $WRAPPER_ROOT/ace:$LD_LIBRARY_PATH

        * When all this is done, hopefully all you'll need to do is
          type:
          
          % make
          
          at the root of the ACE source tree.  This will build the
          static and shared object libraries and build the tests and
	  the sample applications.  

Please note that I'm very receptive to suggestions/contributions for
improving the configuration process.  Eventually, I'd like to replace
the current scheme with something similar to the GNU configure and
autoconf facilities.

CLONING THE SOURCE TREE

        I typically like to support multiple platform builds using the
same ACE source tree.  This idiom is supported by ACE using the
$(WRAPPER_ROOT)/bin/clone.c program.  To build clone, perform the
following steps:

        % cd $WRAPPER_ROOT/bin 
	% make 
	% mv clone ~/bin 
	% rehash

Then create a ./build subdirectory someplace (e.g., under
$WRAPPER_ROOT), and then invoke the top-level Makefile with the
"clone" target, e.g.:

        % cd $WRAPPER_ROOT 
	% mkdir build-SunOS5
	% cd build-SunOS5 
	% make -f ../Makefile clone 
	% setenv WRAPPER_ROOT $cwd 
	% make

This will establish a complete tree of links.  When you do a make in
this directory you will be producing object code that is not stored in
the same place as the original source tree.  This way, you can easily
build another platform in a parallel tree structure.

                       *** VERY IMPORTANT! ***

If you use the "clone trick" discussed above, make sure that the
symbolic links are correctly in place before starting the build.  In
particular, if you plan to clone the tree, it is preferable to do so
before you start a build procedure on the original tree.  This is
because the build procedure create object directories (.obj and
.shobj) and the cloning procedure will clone these directories also.
You would end up with links pointing to object files of another
platform.  If you clone the tree after you've done a build on the
original tree, make sure to remove all ".obj", ".shobj" and (any other
files or directories) in all subdirectories before starting the build
on your cloned tree.

SUPPORTED PLATFORMS AND COMPILERS

The ADAPTIVE Communication Environment has been ported and tested
fairly extensively on the following platforms and compilers:

        * OSF/1, HP-UX, SGI IRIX 5.x, and Sun OS 5.x (a.k.a. Solaris
	  2.x) using Sun CC 3.0.1, Sun C++ 4.0.x, Centerline C++ 2.x,
	  and GNU gcc 2.7.x. 

                . All the source code and tests should build and run
                  without any problems on the Solaris platform using the Sun
                  C++ compilers.

                . Note that earlier version of G++ may not compile certain
                  parts of ACE correctly due to compiler bugs.  The fix is
                  to upgrade to G++ 2.7.0 or greater (using the
		  template repository patches that are available at
		  ftp://ftp.cygnus.com/pub/g++/gcc-2.7.0-repo.gz).

        * Sun OS 4.1.2 using Centerline C++ 2.x, Sun CC 3.x, and Lucid
          Energize 3.2.

                . Note that shared libraries do not interact very well
                  with Centerline C++ or Sun C++ on SunOS 4.1.x.  This is
                  due to odd behavior of the SunOS 4.1.x linker, which (1)
                  does not properly call constructors of global objects
                  within shared libraries and (2) does not call the init()
                  and fini() functions in shared libraries, even though
                  the manual claims that these functions are called!  In
                  particular, this means that the tests in the directory
                  $(WRAPPER_ROOT)/tests/Service_Configurator/IPC-tests/server/
		  will not work for statically linked services...

		  I haven't yet got GNU GCC 2.7.x working on SunOS 4.x
		  since that OS platform doesn't support smart linkers
		  that can remove duplicate template definitions.  If
		  anyone knows the secret for doing this please let me		   
		  know...

        * Sun OS 4.1.x

                . Some versions of SunOS 4.1.x do not contain the
                  /usr/lib/libnsl.a library.  This library seems to be
                  optional since System V Transport Layer Interface
                  (TLI) support is optional on SunOS 4.1.x (in
                  contrast, it's the "preferred" transport interface
                  on Solaris).

                  The best work-around for now is probably to either add a
                  dummy libnsl.a in /lib (which may not be feasible) or
                  simply comment out the line:

                  LIBS          += -lnsl

                  in the
                  $WRAPPER_ROOT/include/makeinclude/wrapper_macros.GNU
                  file.  Naturally, any programs (e.g., the TLI_SAP tests)
                  that use the TLI wrappers aren't going to work!

                  Note that on SunOS 4.x you may get warnings from the
                  linker that "archive has no table of contents; add one
                  using ranlib(1)" for certain libraries (e.g., libASX.a,
                  libThreads.a, and libSPIPE.a).  This occurs since SunOS
                  4.x does not support these features.

	* AIX

		The ACE port to AIX is currently underway.  This
		release contains the latest changes for AIX.  These
		changes assume that the user has installed the AIX patch
		containing the dl*() APIs.  To use these APIs, IBM has
		created a separate product (free to AIX licensees)
		called shared library hookable symbols (or slhs/6000).
		If you don't have this patch, the sv* commands for
		compiling and linking will not be present on the 
		system.

	* Linux
	
		. People have ported bits and pieces of ACE to Linux.
		  I don't have access to this platform so I can't
		  really test them.  However, you'll find config files
		  for Linux $WRAPPER_ROOT/ace.  If you get them to
		  work, please let me know. 

	* Win32 (Windows NT and Windows '95)

		. Most of ACE has been ported to the Win32 API (which
		  includes Windows NT and Windows '95).  The entire
		  release now compiles using the Microsoft Visual C++
		  4.0 compiler (the 2.0 compiler should also work, but 
		  I haven't tested it).  Please compile with the
		  winntace.mak file, which builds ACE as a static
		  library.  We are still in the process of porting
		  to Win32 (e.g., making it a DLL).  Any help you can
		  give us would be *greatly* appreciated.

BUILDING CORBA VERSIONS OF ACE

Note that if you are compiling with IONA's Orbix implementation of
CORBA or Post Modern's version of ORBeline, you'll also need to set
ORBIX_ROOT to point to the root of the Orbix source tree and
ORBELINE_ROOT to point to the root of the ORBeline source tree.  Since
many platforms don't have these CORBA tools the default for ACE does
*not* incorporate them.  Thus, if you are compiling with Orbix or
ORBeline, make sure that you set the symbolic links for
$WRAPPER_ROOT/include/makeinclude/platform_macros.GNU and
$WRAPPER_ROOT/ace/config.h to point to the the config* and platform*
files that have "-orbix" in them!

----------------------------------------

As the ACE wrappers become more widely used I hope developers will
pass back patches and improvements for other OS platforms and
compilers.  If you have a problem compiling the ACE wrappers on other
platforms please let me know of any general solutions that may solve
this problem for others.  However, I am primarily concerned with
supporting cfront 3.x variants of C++ and beyond, rather than older
versions that do not support features such as templates.

