Initial revision

1 files changed, 440 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 00000000000..3e285b5b7b3
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,440 @@
+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
+extensively on the following platforms and compilers:
+
+* Win32 (Windows NT and Windows '95)
+
+	. All 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
+	  recently).  ACE can be built as both a static and dynamic
+	  library, using the Win32 installation process described
+	  below.
+
+* 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 and SunOS platforms using the 
+	  Sun C++ compilers.
+
+* 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 and SCO 4.2
+
+	. ACE has been ported to Linux and SCO UNIX using the GNU G++
+	  2.7.2 compiler.
+
+* SGI IRIX 5.x
+
+	. ACE builds fine using the SGI C++ and GNU GCC compilers for
+	  IRIX 5.x.  I haven't tried this on IRIX 6.x, but I assume 
+	  that will work too.  If anyone can get ACE working with 
+	  IRIX 6.x pthreads please let me know.
+
+* HP-UX 9.x and 10.x
+
+	. The current HP/UX C++ compiler is incredibly lame and has
+	  problems compiling ACE templates and achieving template
+	  closure.  I've heard that the next release is better...
+	  In the meantime, you might try using GNU GCC or SunC++
+	  on HP/UX.
+
+* OSF/1 3.2
+
+	. The current OSF/1 5.1 C++ compiler is also rather poor and there
+	  seems to be no way to build shared libraries with templates
+	  on OSF/1.  I've also heard that the new version of this
+	  compiler (5.3) is better.  Again, you might try GNU GCC.
+
+* UnixWare 2.01
+
+	. Steve Huston has ported ACE to work with UnixWare 2.01 and
+	  its standard C++ compiler.
+
+* VxWorks
+
+     	. David Levine has ported ACE to VxWorks 5.2 using the
+	  GreenHills 1.8.7 compiler. 
+
+* MVS
+
+	. Chuck Gehr has ported ACE to IBM MVS.
+
+----------------------------------------
+
+COMPILING ACE WITH GNU C++
+
+If you use the GNU GCC C++ compiler please note the following:
+
+	. Earlier versions of GNU GCC may not compile certain
+	  parts of ACE correctly due to compiler bugs.  
+	  Please upgrade to GCC 2.7.2 or greater.
+
+	. Make sure to update your gcc "config.status" file -
+	  this specifies whether your gcc install uses, for
+	  example, Solaris's "/usr/ccs/bin" binary utils or
+	  GNU binary utils. 
+
+--------------------------------------------------
+
+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/OS.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 STATIC AND DYNAMIC LIBRARIES.
+
+The installation process for NT is a bit different than UNIX.  First,
+I assume you're using MSVC++ 4.0(things are a little different for the
+2.0 version...).
+
+0. SET UP THE ACE FILES.
+
+   Create a directory accessible via Windows NT (e.g., C:\ACE) 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).
+
+   The easiest thing to do is just use the default ace.mpd and ace.mak
+   files distributed with the release.  Open workspace ace.mpd to
+   build ACE as a DLL.  This included project assumes that you have
+   set the "global" include path to include $WRAPPER_ROOT.  This can
+   be done via the following MSDEV menu item:
+
+   Tools/Options/Directories/Show_Directories_For:Include_Files.
+
+   If you choose not to use the given project, then the following
+   bullets 1 through 6 explain how to build ACE with MSDEV. 
+   
+1. CREATE A PROJECT WORKSPACE. 
+
+   Start by making a new project.  It should be rooted at
+   $WRAPPER_ROOT.  We normally browse to $WRAPPER_ROOT, and select
+   "ace" as the project name.  This will cause MSDEV to use the
+   $WRAPPER_ROOT/ace directory to store the project files.  The actual
+   directory and project name are unimportant, but we'll assume you
+   named the project "ace."  Select the dynamic link library option
+   and say "ok."  By default, the config-win32*.h files are set up to
+   build DLLs.  If you choose to build ACE as a static library you'll
+   need to unset ACE_HAS_DLL in the config-win32*.h file and select
+   the static link library option when creating a project workspace.
+
+2. INSERT FILES INTO PROJECT. 
+
+   Go into the Insert menu and select "Files into project".  If you're
+   building a static library, select all the *.cpp files in
+   $WRAPPER_ROOT/ace into the project.  If you're building a DLL, you
+   need to omit the files in ACE which contain template class
+   definitions.  You can find out which files this is by looking at
+   the TEMPLATE_FILES target in the $WRAPPER_ROOT/ace/Makefile.
+   
+   Once you've selected the files and pressed "ok" it should take a
+   few seconds or so to for MSDEV to create the project.  (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.)  When
+   including the files on windows 95, it may ask you to select fewer
+   files than *.cpp.  Just do A-M and N-Z or something similar.
+
+3. SET THE INCLUDE PATH. 
+
+   Go into Options section of the Tools menu.  Add the $WRAPPER_ROOT
+   directory to the default directory search path.  This is necessary
+   since all ACE #include files refer to themselves via ace/Foo.h.
+   Then add $WRAPPER_ROOT\ace to the default library search path.
+   This means that you can now use relative paths for linking apps
+   with ace.lib.  You may skip this step if you have set
+   Tools/Options/Directories/Include_Files to include $WRAPPER_ROOT.
+
+4. SET UP THE LINKER. 
+
+   You might want to link with the wsock32.lib into the ACE project,
+   as well, so that you don't have to include it with every
+   applications link setup.  Do this by including wsock32.lib in the
+   project through Insert/Files_into_project.
+
+   When building a DLL: In order to allow standard C library functions
+   to share common variables across DLL and exe boundaries, we must
+   ensure that both DLL and exe are using the same libraries.  Go to
+   Build/Settings/C++/Category:Code_Generation.  Set Use run-time
+   library to "Multithreaded DLL" or "Debug Multithreaded DLL"
+   depending on whether you're building a release or a debug version
+   respectively.
+
+   When building a static lib: Go to
+   Build/Settings/C++/Category:Code_Generation and set run-time
+   library to "Debug Multithreaded" (or just "Multithreaded").
+
+5. BUILD.
+
+   Go to the Build menu and select "Build ace.{lib,DLL}".  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, native NTFS, etc.).  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...).
+   
+   At this point, the compiler should be happily chugging away on your
+   files.  
+
+6. USING ace.lib.
+
+   When the compilation is done, you should have a static or dynamic
+   library called ace.lib.  You can use this to link with test 
+   applications (such as those in the $WRAPPER_ROOT/examples directory).  
+   This process is described below.
+
+Making test applications for Windows NT.
+
+0. CREATE THE PROJECT.
+
+   As before, make a new project for each application.  We've been
+   using Console Applications.  Insert the appropriate .cpp files into
+   the project.
+
+1. SET THE INCLUDE PATH.
+
+   In Build/Settings/C++/Category:Preprocessor, add $WRAPPER_ROOT to
+   "Additional include directories". If you've set the
+   Tools/Options/Directories/Include_Files to include $WRAPPER_ROOT,
+   then you don't need to do this.
+
+2. SET UP THE LINKER.
+
+   You'll also need to tell MSVC++ what libraries to link with.  In
+   Build/Settings/Link, add "$WRAPPER_ROOT/ace/Debug/ace.lib" to the
+   Object/library modules.  If you've set
+   Tools/Options/Directories/Library_Files to include
+   $WRAPPER_ROOT/ace, you can just add "ace.lib" to the Object/library
+   modules instead of the complete path.
+
+   When using ACE as a DLL: Go to
+   Build/Settings/C++/Category:Code_Generation.  Set Use run-time
+   library to "Multithreaded DLL" or "Debug Multithreaded DLL"
+   depending on whether you're building a release or a debug version
+   respectively.
+
+   When using ACE as a static lib: Go to
+   Build/Settings/C++/Category:Code_Generation and set the run-time
+   library to "Debug Multithreaded" (or just "Multithreaded").
+
+   If you're using WinSock, you will also need to add wsock32.lib to
+   this line if you haven't inserted into the ACE project already.
+
+3. BUILD.
+
+   You should now be able to build the .exe.
+
+4. BUILDING ACE ON A WIN32 MACHINE THAT LACKS A NETWORK CARD 
+
+You may want to run ACE on a non-networked machine. To do so, you must
+install TCP/IP and configure it to ignore the absence of a network
+card.  This is one method:
+
+        1.  Run Control Panel
+        2.  Choose Network from Control Panel
+        3.  Add Adapter: MS Loopback Adapter
+        4.  Configure MS Loopback Adapter with 802.3 (default)
+        5.  Add Software: TCP/IP Protocol
+        6.  Configure TCP/IP Protocol with a valid IP address and subnet mask.
+            Leave everything else at the default settings.
+        7.  Add Software: Workstation
+        8.  Exit and Restart System
+        9.  Run Control Panel again
+        10. Choose Services from Control Panel
+        11. The following services are not necessary and may
+            be set to Disabled Startup:
+                Alerter
+                Computer Browser
+                Net logon
+                Messanger
+        12. Choose Network from Control Panel
+        13. Confirm the following setup. This is all you need to run Orbix:
+                Installed Software:
+                Computer Browser
+                MS Loopback Adapter Driver
+                TCP/IP Protocol
+                Workstation
+                Installed Adapter Cards:
+                MS Loopback Adapter
+
+--------------------------------------------------
+
+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 Visigenix'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.