path: root/INSTALL

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
	  $(ACE_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 $ACE_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.  aC++ is better - it builds the ACE library ok
	  but crashes while compiling some examples and test programs.
	  GNU GCC and SunC++ have also been known to work.

	. There are a number of config files for HP in the ace directory.
	  If you are using an HP compiler (HP C++ or aC++) the file
	  config-hpux-10.x-hpc++.h is the preferred config file.
	  config-hpux-10.x.h is compiler-independent, and is included by
	  config-hpux-10.x-hpc++.h.  People maintaining config for other
	  compilers are encouraged to follow this model - put compiler-
	  specific settings in the config-hpux-<compiler>.h file and
	  include config-hpux-10.x.h from there.

* OSF/1 3.2 and 4.0 (a.k.a. Digital UNIX 4.0a) 

	. The current OSF/1 C++ 5.4 compiler still seems to have
	  problems with ACE's templates. It compiles the lib and test
	  programs, although giving warnings about template usage.
	  Most tests run, some dump core.  Hopefully newer compiler
	  releases will alleviate these problems.  
 
 	  GNU gcc 2.7.2.1 compiles without problems. All tests run
	  (besides minor problems).  Thanks to Thilo Kielmann
	  <kielmann@informatik.uni-siegen.de> and David Trumble
	  <trumble@cvg.enet.dec.com> for help with this port. 

* UnixWare 2.01

	. Steve Huston has ported ACE to work with UnixWare 2.01 and
	  gcc 2.7.2.

* VxWorks

     	. David Levine has ported ACE to VxWorks 5.2 and 5.3 using the
	  GreenHills 1.8.8 compiler. 

* MVS OpenEdition

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

	. Make sure that the linker invoked by GCC produces code 
	  that initializes static objects.  Please see GCC's 
	  documentation for using "collect2."

	. By default, gcc (thru version 2.7.2, at least) uses
	  implicit template instantiation.  Besides wasting space,
	  this breaks the use of ACE_Singleton:  instead of one
	  singleton instance, there could be one instance per object
	  (.o) file that "sees" the template.  Therefore, we have
	  overridden this default in ACE by enabling the
	  -fno-implicit-templates option to CCFLAGS in all
	  include/makeinclude/platform_*.GNU files that set CXX to g++.

	  The disadvantage of this approach is that you must
	  add template specializations for all templates that your
	  application uses to your own code.  (The ACE libraries are
	  self-contained:  you don't need to add the templates that
	  they use internally.)  Examples of template specializations
	  occur in quite a few ACE .cpp files; see
	  apps/Gateway/Gateway/Proxy_Handler.cpp for one example.
	  An easy way to figure out what template instantations are
	  need is to try to build your executable and pipe the output
	  through c++filt.  The linker will report the missing
	  instantiations as undefined symbols.  Iteration may be
	  necessary, if the template instantiations themselves reference
	  other templates.

	  Alternatively, you could apply the Cygnus template repository
	  patches and use the -repo option instead of
	  -fno-implicit-templates.  Please see the g++ FAQ and gcc
	  manual for more information.  The g++ FAQ indicates that
	  a new implementation of templates planned for version 2.8
	  will eliminate the restriction against static data members
	  in template classes, which would allow ready implementation
	  of a correct ACE_Singleton.  A final alternative is to
	  remove the -fno-implicit-templates option from the CCFLAGS
	  macro in your include/makeinclude/platform_macros.GNU, and
	  thereby use the default g++ implicit template instantiation.

	  Thanks to Thilo Kielmann <kielmann@informatik.uni-siegen.de>
	  for reporting the problem with ACE_Singleton on g++, and
	  for helping to find and implement these solutions.

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

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 ACE_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 ACE_ROOT /home/cs/faculty/schmidt/ACE_wrappers 

   The ACE recursive Makefile system needs this information.

3. Edit the $ACE_ROOT/ace/OS.h file to update things like default
   hostname and port numbers you'd like the programs in the
   $ACE_ROOT/{apps,tests} directories to use by default.
 
4. Set the $ACE_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 $ACE_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 $ACE_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 $ACE_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 $ACE_ROOT in
   the following discussion.  Then copy config-win32.h 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 $ACE_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
   $ACE_ROOT.  We normally browse to $ACE_ROOT, and select
   "ace" as the project name.  This will cause MSDEV to use the
   $ACE_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
   $ACE_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 $ACE_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 $ACE_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 $ACE_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 $ACE_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 $ACE_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 $ACE_ROOT to
   "Additional include directories". If you've set the
   Tools/Options/Directories/Include_Files to include $ACE_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 "$ACE_ROOT/ace/Debug/ace.lib" to the
   Object/library modules.  If you've set
   Tools/Options/Directories/Library_Files to include
   $ACE_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
$(ACE_ROOT)/bin/clone.c program.  To build clone, perform the
following steps:

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

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

        % cd $ACE_ROOT 
	% mkdir build-SunOS5
	% cd build-SunOS5 
	% make -f ../Makefile clone 
	% setenv ACE_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
$ACE_ROOT/include/makeinclude/platform_macros.GNU and
$ACE_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.