diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 440 |
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. |