INSTALLATION NOTES FOR THE ADAPTIVE COMMUNICATION ENVIRONMENT (ACE)

---------------------------------------------------------- 
The file explains how ACE to build ACE on the various UNIX and Win32
platforms that it has been ported to.  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.
----------------------------------------------------------

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, Sun OS 5.x/4.x (a.k.a. Solaris
  2.x/1.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.x 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...

	  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 assumes 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

	. Most of ACE has been ported to Linux.  However, I don't have
	  access to this platform so I can't really test it.  If you
	  get ACE to work completely on Linux, 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.

INSTALLATION PROCESS FOR UNIX 

The installation process for installing ACE on UNIX is relatively
simple (the installation process for Windows NT is different, please
see the section below).  Here's what you need to do:

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

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

3. 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.
 
4. 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.

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

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

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

INSTALLATION PROCESS FOR WINDOWS NT

The installation process for NT is a bit different than UNIX.  First,
I assume you're using MSVC++ 2.0 or 4.0 (things are a little different
for each of these...).

0. Create a directory accessible via Windows NT and copy all of ACE
   into it.  This directory will be $WRAPPER_ROOT in the following
   discussion.  Then copy either config-win32-msvc4.0.h or
   config-win32-msvc2.0.h (depending on your compiler of course) to
   config.h.  Note that files like ChangeLog may do strange things on
   NT since they are symbolic links (which aren't supported under NT).

1. Start by making a new project (e.g., "winace").  It should be
   rooted at $WRAPPER_ROOT/ace.  You'll need to build ACE as a static
   library for now (we're working on making it a DLL).  MSVC++ will
   create a directory called $WRAPPER_ROOT/ace/winace/.  This is where
   the object files for the build will be placed.

2. Go into the Insert menu and select "Insert all files into project".
   Then, select all the *.cpp files in $WRAPPER_ROOT/ace into the
   project.  This make take a minute or so.  (Note that in MSVC2.0
   there isn't an Insert menu, so go into the Project Menu and then
   "Files" and from there insert all the *.cpp files.

3. Go into "Project Settings" option of the Build menu, select C/C++
   options and choose the Category "preprocessor".  Then add the
   include directory as an absolute path to $WRAPPER_ROOT to the list
   of additional include directories.  This is necessary since all ACE
   #include files refer to themselves via ace/Foo.h.  Then go to the
   File menu and do a "Save All".  (Note that on MSVC2.0 you'll have
   to add your path to $WRAPPER_ROOT under the Menu Tools->Options,
   then select Directories, then Show Directories for "Include
   Files").

4. Go to the Build menu and select "Build winace.lib".  The first time
   this happens it will rebuild all the dependencies.  This may take a
   while (i.e., 3 to 15 minutes, depending on whether you use Samba,
   PC-NFS, or native NT).  The whole process will seem to generate
   lots of errors and warning about not finding many UNIX header
   files, etc.  Just ignore these errors/warnings.  They are due to
   the lame MSVC++ compiler that doesn't pay attention to the #ifdefs
   when computing the dependencies.  Eventually, this process will
   stop and from you won't have to rebuild the dependencies then on
   (thank God...).
   
5. At this point, the compiler should be happily chugging away on your
   files.  When it's done, you should have a static library called
   winace.lib.  You can use this to link with test applications (such
   as those in the $WRAPPER_ROOT/tests directory).  Note that you'll
   need to make separate projects for these, as well.

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.

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.

