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 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 and David Trumble for help with this port. * 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 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 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 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 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 $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.