### Building and Installing ACE and Its Network Services

#### Synopsis

The file explains how to build and install ACE and its Network Services on the various OS platforms and compilers that it has been ported to. Please consult the ChangeLog file to see whether any recent changes to the release will affect your code. You also might want to read the ACE FAQ before building and installing ACE. In addition, you might want to check out our development process, as well. And as you start working with ACE, you might want to consult the ACE Frequently Made Mistakes page. If you encounter any problems or would like to request an enhancement, then use our bug tracking system to submit a report.

#### Document Index

- Supported Platforms and C++ Compilers
- Installation Notes for Supported Platforms
- Compiling ACE with GNU g++
- Compiling ACE with egcs
- Building and Installing ACE
- Building and Installing ACE Network Services
- What Do I Need to Build for TAO?
- System Resource Requirements
- Advanced Topics

### Supported Platforms and C++ Compilers

The following table summarizes platforms on which ACE runs:

Fully supported, i.e., continually tested and used daily | Solaris 2.5, 2.6, and 7, Windows NT 4.0 (MSVC++ 5.0, and 6.0), Linux/Intel, Linux/Alpha, VxWorks, LynxOS, Digital UNIX 4.0 and 5.0, HP/UX 10.x and 11.x, AIX 4.x, and IRIX 6.x
Nearly fully supported, i.e., periodically tested | Windows 95, MVS, DEC Alpha Windows NT (MSVC++ 5.0, 6.0), Chorus, QNX Neutrino 2.0, PharLap TNT Embedded ToolSuite 9.1
Partially supported, i.e., infrequently tested | Windows NT (Borland C++ Builder 4.0 and IBM VisualAge C++), Windows CE, Tandem, SCO, UnixWare, SunOS 4.x, FreeBSD, NetBSD, Linux/PPC.
Planned support, i.e., pending | pSoS,

Any UNIX/POSIX/Win32 variation is a potential target platform for TAO. If you have porting questions or have a problem compiling the ACE wrappers on the platforms shown above please send email to either ACE Newsgroup or the ACE mailing list and we'll try to help you fix the problems.

### Installation Notes for Supported Platforms

- Win32 (Windows NT/i386, NT/Alpha 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++ 5.0, and 6.0 compilers (the 2.0 compiler may also work, but we haven't tested it recently). ACE can be built as both a static (LIB) and dynamic (DLL) library, using the Win32 installation process described below.

  Please see the Non-static ACE_Object_Manager discussion below.

  We've also added some support for Borland C++ Builder 4.0 and IBM's VisualAge C++ compiler. Since we don't have these compilers we rely on the ACE+TAO users community to maintain these ports. Therefore, please send email to the ACE mailing list if you run into problems.

- Windows CE

  Most of ACE has been ported to Windows CE using Visual C++ 5.0 with CE Toolkit. ACE has been tested on x86 Emulator and an HP 360LX with an SH series CPU. Please be sure to read this file (CE-status.txt) for up-to-date information about ACE on CE. ACE can only be built as DLL library now.

- Sun OS 5.x/4.x (a.k.a. Solaris 2.x/1.x, Solaris 7) using Sun CC 3.0.1, Sun C++ 4.2 and 5.x, Centerline C++ 2.x, GNU gcc 2.7.x and later (except 2.8.x), and KAI C++ 3.3.

  All the source code and tests should build and run without any problems on Solaris 2.5.1, 2.6 and 7 platforms using the Sun C++ compiler. We use this version/patchlevel of Sun C++:

            CC: WorkShop Compilers 4.2 21 Apr 1997 C++ 4.2 patch 104631-02

  There are likely to be build problems with older versions or different patchlevels of Sun C++.

  Thanks to Susan Liebeskind <shl@janis.gtri.gatech.edu> for providing the following useful information:

  The home page for Sun technical patches is http://access1.sun.com. Searching for 104631 will bring you to a page allowing you to access the latest version of the C++ 4.2 patches.

  By default, ACE uses both the Solaris and POSIX thread interface. To disable use of the Solaris thread interface, add `-D_POSIX_PTHREAD_SEMANTICS` to the `CFLAGS` in your `ACE_wrappers/include/makeinclude/platform_macros.GNU`. See the Solaris Intro (3) man page for more information.

  To disable ACE thread support completely, build with the `threads=0` make flag. See the Makefile Flags section below for more information on make flags.

  If you use g++ or egcs on Solaris 7, you might need to rebuild it on a SunOS 5.7 (Solaris 7) host. Some versions of g++ and egcs provide replacements for system header files. The replacements on older SunOS systems are not compatible with the SunOS 5.7 system headers. See David Levine's Hints page for instructions on how to build egcs on a SunOS 5.7 host, using a g++ or egcs that was built on an older SunOS host.

  The Sun/C++ 5.0 compilers has several problems with templates, we have worked around most of them but this is not a compiler that we test very often. Hopefully as new patches for the compiler show up we will be able to make that our compiler of choice on Solaris.

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

  If you are using AIX 4.2.1 or later, this patch isn't needed; the dynamic library APIs are included in the base operating system.

  However, another patch may be needed. Thanks to Susan Liebeskind <shl@janis.gtri.gatech.edu> for submitting the following useful information:

  When building on AIX 4.2.1, using the xlC V3.1 compilers, you may get the following error when building the ACE shared library.

      makeC++SharedLib_r -p 0 -o libACE.so  -bI:/lib/pse.exp  -L/usr/local/src/ACE_wra
      ppers/ace -L./ -ltli_r -ldl libACE.a
      ld: 0711-317 ERROR: Undefined symbol: .__CurrentException
      ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information.
      make: *** [libACE.so] Error 8

  To fix this error, you need a patch to the supporting xlC related libraries. To obtain this patch, go to the IBM public patch website, and retrieve the patch PTF U453697, or its successor, for xlC.

  You may wish to retrieve this patch with the fixdist tool, also available at the website. Installation of this patch will install patched versions of the C++ libraries, which correctly define this symbol.

  To build ACE on AIX with Visual Age C++, use the $ACE_ROOT/ace/ace-dll.icc (or ace-lib.icc) along with the appropriate version-specific config file (e.g. config-aix-4.3.x.h). All of the version-specific config files set the version number macros and include the general config-aix-4.x.h file which has support for all of the OS versions and compilers supported on AIX. Using the general config file is the recommended practice for egcs, C Set++, and IBM C/C++ compilers. However, the Visual Age C++ compiler does not make use of the platform_macros.GNU file, which is how the OS version information generally gets set.

  BTW, here's a technique from Rob Jordan <jordan@hursley.ibm.com> that can reduce the size of the ACE libraries by about one third, and can also be applied to applications. It works by optimising the sharing of template functions, which are created in an ``unusual'' way under AIX. It also speeds up compilation.

  Here's how to optimise the ACE library generation:

  Look at the Makefile in `$ACE_ROOT/ace`. Create a file called `ACE_All_Src.cpp`, and add a line to #include each of the source files listed under `FILES=` in the Makefile. Create a file called `ACE_All_Tmp.h` and add a line to #include each of the .h files listed under `TEMPLATE_FILES=` in the Makefile. Now update the Makefile so that `FILES=ACE_All_Src` and `TEMPLATE_FILES=ACE_All_Tmp`.

- Linux

  ACE has been ported to Linux on Intel, Alpha, and PowerPC platforms. If you use a RedHat 5.x distribution, it's best to use RedHat 5.1 or later. ACE works without any modifications on RedHat 5.1, 5.2, and 6.0, and on Debian 2.1 on both Intel and Alpha; use the `include/makeinclude/platform_linux_lxpthreads.GNU` and `ace/config-linux-lxpthreads.h` platform/config files. The same files can be used on PowerPC, with LinuxPPC 1999 (R5), with glibc 2.1.1.

  If you run out of memory, it's easy to add virtual memory on Linux. Please see the `mkswap` man page. You'll need around 256 to 300 Mb of virtual memory (RAM + swap) to compile all of ACE+TAO. The System Resource Requirements section has some suggestions on how to reduce the memory requirement.

  The glibc 2.0 dynamic loader isn't thread safe. If you want to use the Invocation API you'll have to set `LD_BIND_NOW=true`. If you want to use `dlopen`, you should use `RTLD_NOW`. The dynamic loader in glibc 2.1 is thread safe.

  The ACE `Tokens_Test` hangs with egcs 1.1b on Linux. It runs properly when built with egcs 1.0.2 and later. All other ACE tests run properly with these egcs 1.0.2 and later.

  NOTE: The TAO NameService uses IP multicasting by default, though it is not required. IP multicast on Linux requires the following:

  - Enable IP multicast in the Linux kernel. It is enabled in the default RedHat 5.1 kernel. In older distributions, you can enable it by rebuilding your kernel with CONFIG_IP_MULTICAST enabled.

  - Enable IP multicast in ACE. It is enabled by default in `ace/config-linux-common.h`. If you don't use IP multicast, add `#define ACE_HAS_IP_MULTICAST 0` to your `ace/config.h` before building ACE.

  - There must be a network interface that is up and supports multicast. If you have linuxconf, it's easiest to use that to add a network route for multicast (224.0.0.0) on one of your network interfaces, such as `eth0`. If you don't have or use linuxconf, try adding a multicast routing table entry using something like this:

                     # route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0

  With RedHat 5.0, you'll need some updates and possibly some patches to get ACE working with LinuxThreads. Some of the patches are necessary with Alpha CPUs and with some older kernels. egcs 1.0.1 can also be used, but it may need patches, described there, as well.

  NOTE: Be careful when installing egcs on RedHat systems. If you don't remove your old gcc and libg++ RPMs, it's best to install egcs in a different directory than `/usr`, such as `/usr/local`, and set your `PATH` and `LD_LIBRARY_PATH` accordingly.

  Some of the ACE tests fail on older, pre-glibc2 Linux platforms, such as RedHat 4.2. The problems are with threads and thread-specific storage.

- SCO UNIX

  ACE has been ported to SCO UNIX using the GNU g++ 2.7.2 compiler. Arturo Montes <mitosys@colomsat.net.co> maintains this code. In addition, he also maintains a version of FSU pthreads.

- SGI IRIX 5.x and 6.x

  ACE used to build fine using the SGI C++ and GNU GCC compilers for IRIX 5.x. It has been ported to IRIX 6.x using the SGI MipsPro 7.1 C++ compiler; be aware that in IRIX 6.2 there is a number of patches that have to be installed and exceptions appear to fail with the O32 ABI. Please check the config files for the details.

- HP-UX 9.x, 10.x, and 11.00

  HP sells 2 C++ compilers for HP-UX 10.x and 11.00. If you are using 9.x, there's only the first one.

  - HP C++ - this is CC, HP's cfront-based compiler. As of ACE 4.4, it can be used, but some people have problems with templates. Caveat emptor. It's been said that you should run version 10.24, if not later.
  - HP aC++ - this is aCC, HP's new, ANSI compiler. It handles ACE pretty well. You should use version A.01.18 (or higher) on HP-UX 10.x and version A.03.13 (or higher) on HP-UX 11.00.

  On HP-UX 10.20, a patch is required to compile ACE. The exact patch number depends on the platform - check with HP's patch database to locate the exact patch or its successor. For 9000 700 series machines it is PHKL_8693 (s700 10.20 sys/time.h fix for select(2)/C++ defects).

  Also see further notes on this platform at Riverace's HP-UX Hints page.

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

  The Digital UNIX C++ 5.4 through 5.7 compilers have problems with ACE's templates. They compile the lib and most of the test programs, although they warn about template usage. Most tests run, some dump core. If you use a 5.x version of cxx, be sure to set the CXX_VER variable to CXX_5, either on your make command line or in an environment variable. The ACE Makefiles assume by default that the cxx version is 6.x or later.

  CXX 6.0 and 6.1 are much improved over 5.x: V6.0-020, V6.1-025, and later build all of ACE cleanly. All of the tests in ACE_wrappers/tests run successfully with CXX 6.0 and CXX 6.1. Please note that problems have been reported with some versions of CXX 6.1, notably versions -021 and earlier. It's best to use V6.1-022 or later.

  NOTE: if you use Digital UNIX 4.0f or later, you must use `ace/config-tru64.h` instead of `ace/config-osf1-4.0.h`. `ace/config-tru64.h` can be used for all supported compilers on any version of Digital UNIX after and include 4.0. And, with 4.0f and later when using Digital CXX, you must use `include/makeinclude/platform_tru64_cxx.GNU` instead of `include/makeinclude/platform_osf1_4.0.GNU`. 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.

- FreeBSD

  FreeBSD is a fast evolving platform. However, it has the advantage of having standard releases. At this moment, ACE is only perodically tested against -stable (3.1R) and we rely a lot on FreeBSD users' feedbacks.

  Notice that on older FreeBSD, `ld.so` only looks for so libraries with version number appended. ACE makefiles create symlink for most shared libraries if `versioned_so` is defined to 1 in `$ACE_ROOT/ace` with appropriate ACE version. However, this does not work for libACE.so itself so you have to create it manually (If you figure out how to do this, please let us know) like this:

  `ln -sf $ACE_ROOT/ace/libACE.so $ACE_ROOT/ace/libACE.so.4.5`

  On newer FreeBSD (3.0 or later,) this is no longer necessary.

- NetBSD

  Like older FreeBSD, NetBSD's `ld.so` also requires versioned .so files.

- UnixWare

  Steve Huston <shuston@riverace.com> has ported ACE to work with UnixWare 2.01 and g++.

  Ganesh Pai <gpai@voicetek.com> subsequently did the port for version 2.1.2, also with g++.

- Chorus

  Wei Chiang <chiang@tele.nokia.fi> has ported ACE to Chorus 3.1 using GNU g++ 2.7.2.

- LynxOS

  ACE builds and runs properly on LynxOS 3.0.0 for Intel and PowerPC targets. ACE's Naming_Test fails; it is disabled in `ACE_wrappers/tests/run_tests.sh`.

  If you run out of memory on LynxOS, these might help:

  - Increase the limits in `/etc/starttab`, then logout and login again. We use these limits:

        # Data, stack, and core file limits (in Kbytes)
        240000
        80000
        102400

  - Enable or expand virtual memory, with something like:

        # mkcontig /swap 320
        # prio 17 vmstart /swap

    See the `mkcontig` and `vmstart` man pages, and `/bin/rc`.

  Please see the comments in the ACE platform_lynxos.GNU file for information on, and an example of, tailoring for your particular platform.

  We actively maintain ACE on LynxOS 3.0.0. It should build and run on LynxOS 2.5, but we no longer test on that OS version.

  NOTE: if you want to use IP multicast on LynxOS, be sure to add this line to your `/net/rc.network`, and reboot:

              /bin/route add "224.0.0.0" "$my_name"

  Dave Mayerhoefer <davem@lynx.com> has ported ACE to LynxOS 2.5 using GNU g++ 2.7.2. However, you may need to apply some patches to LynxOS to get ACE working.

- VxWorks

  David Levine <levine@cs.wustl.edu> has ported ACE to VxWorks 5.2/5.3/5.3.1/5.4 with the GreenHills 1.8.8/1.8.9 and g++ compilers that are distributed with VxWorks/Tornado. An anonymous contributor has also provided notes for using ACE with VxWorks 5.1.

  Tornado II/VxWorks 5.4 support IP multicast. That is not enabled by default in ACE for VxWorks, because it probably depends on kernel configuration. To enable it, add `#define ACE_HAS_IP_MULTICAST` to your `ace/config.h`.

  In addition to all of the other benefits of ACE, it helps work around some deficiencies with VxWorks 5.3/5.3.1. Some of these apply only with g++, at least thru version 2.7.2. That is the version that is shipped with Tornado 1.0.1/ VxWorks 5.3.1. The problems are:

  1. The program entry point cannot be called ``main'' with g++. ACE renames it to ``ace_main'' (configurable via ACE_MAIN) on VxWorks. While this may seem trivial, it is important with legacy code. ACE itself ran into this problem.

  2. argc/argv isn't used with VxWorks entry points. ACE provides a wrapper function that transparently converts shell command line arguments to argc/argv form. See below for details.

  3. Unsigned long long support is not available with the g++ that is distributed with Tornado 1.0.1/VxWorks 5.3.1, or with GreenHills 1.8.8. The documentation says that it is supported by g++, but try using it :-) Wind River technical support verified that it doesn't work. ACE provides its own 64-bit unsigned integer type, ACE_hrtime_t, so you don't even have to worry about this problem if you use it.

  4. There a gory problem with munch that is severely aggravated by the presence of a static in the Wind River/g++ iostream.h. ACE hides this and provides an easy-to-use workaround in the very unlikely situation where it becomes a problem. Please see ace/config-vxworks5.2-g++.h for more information.

  In addition, as noted below following the discussion of the g++ -fno-implicit-templates option, -fno-implicit-templates is broken for x86 targets. And, -O2 is not supported on some targets.

  Please note that ACE uses one of the spare fields in the Wind River task control block, spare4, for thread- specific storage. This field is specified in only one place, in ace/OS.i, so it can easily be changed to one of the other spare fields, if necessary.

  Versions of ACE from 4.3.3 and beyond destroy dynamically allocated singletons in the ACE library. But, they may not properly destroy some static objects. If you have trouble running a program multiple times, it may be necessary to unload the module, using unld, and reload it between runs. Alternatively, you could try calling `cplusDtors` and then `cplusCtors` between runs.

- MVS OpenEdition

  All of ACE has been ported to OpenEdition by Chuck Gehr <gehr@sweng.stortek.com>. The ACE library, all the tests and most of the examples and apps build clean. There are still some problems that need to be ironed out:

  MVS does not support the dynamic linking dl...() calls that the Service Configurator uses to dynamically link services at run time. As a result, all the examples and apps that use a svc.conf file (for dynamically configuring service objects) do not work, however, most of these apps can be built/run statically. Also, the Svc_Conf_l.cpp and Svc_Conf_y.cpp files are generated using flex and yacc on a ascii (not ebcdic) machine and as a result they don't work very well with ebcdic svc.conf files. We should be able to regenerate these files on MVS but MVS doesn't have flex. This is something that needs to be done.

  Some of the tests do not execute properly. This is a minority and over time the goal is to get to 100%.

  The make scheme for some of the apps still doesn't work perfectly on MVS. This is mainly due to the way shared libraries are handled on MVS. See additional build tips for MVS for more on this.

- QNX Neutrino

  ACE has been ported to QNX Neutrino 2.0. We cross-compile for Neutrino on a QNX4 host using g++ 2.8.1, using the ace/config-qnx-neutrino.h and include/makeinclude/platform_qnx_neutrino.GNU configuration files. Many of the ACE tests succeed, though some fail. As the porting effort progresses, we hope to eliminate these failures. If you know of fixes, please send them to us.

- PharLap TNT Embedded ToolSuite (ETS)

  ACE has been ported to PharLap's TNT Embedded ToolSuite (ETS) version 9.1. The port is being tested with Microsoft Visual C++ 6.

  To build for PharLap, use the ace/config-pharlap.h configuration file, and the instructions for building on Win32. Building the ACE library is the same as for regular Win32 platforms, except you choose one of the PharLap ETS configurations to build within Visual C++. Only static library configurations are available for PharLap at this time. For an example of how to build binaries, see the tests directory. The tests_pharlap_msvc.lnk file is a LinkLoc commands file that the ACE tests are built with. It is likely that local sites may need to adjust this file for their target environment.

  If you have any fixes or suggestions for improving this port, please contact Steve Huston.

#### Compiling ACE with GNU g++

If you use the GNU GCC g++ compiler please note the following:

- If you have problems building shared libraries with egcs 1.1 or 1.1.1 on SunOS 2.5 or 2.5.1 that look like this:

              /usr/ccs/lib/libgen.a(reg_compile.o): In function `_get_vars_storage':
              reg_compile.o(.text+0x30): relocation truncated to fit: R_SPARC_GOT13 free

  the suggested workaround is to comment out the `ACE_HAS_REGEX` `#define` in `ace/config-sunos5.5.h`. Or better, create an `ace/config.h` that looks like:

            #ifndef ACE_CONFIG_H
            // ACE_CONFIG_H is defined by the following #included header.

            #include "ace/config-sunos5.5.h"

            #undef ACE_HAS_REGEX

            #endif /* ACE_CONFIG_H */

  We don't know what causes the link problem, though the workaround solves it.

- With g++ 2.8.0, an internal compiler error is raised when trying to compile ACE_Map_Manager instantiations. One workaround is to disable optimization. The easiest way to do that is:

      % make optimize=0

  Or, you can edit your include/makeinclude/platform_sunos5_g++.GNU, and comment out the `OCFLAGS` line.

- ACE/TAO don't seem to build well with g++ 2.8.1. We routinely use egcs 1.1.1 (on Solaris) and 1.1.2, and recommend those versions.

- Earlier (prior to 2.7.2) versions of g++ may not compile certain parts of ACE correctly due to compiler bugs. Please upgrade to g++ 2.7.2 or greater.

- Make sure to update your gcc `config.status` file. This file is produced when installing gcc; it specifies where to install the binary files that gcc uses. For example, it specifies whether to use Solaris's `/usr/ccs/bin` binary utils or GNU binary utils. The `config.status` file is an output of the gcc `configure` script; it is preferable to use the `--prefix` option to `configure` instead of hacking its output.

- If you are getting weird link errors when building libACE on Solaris you are probably using the GNU linker. Try using the Sun linker (/usr/ccs/bin/ld) instead. Note that gcc first looks for the GNU linker if it is installed along with gcc. The only way to not use the GNU linker is to delete it from the installation or to build your own compiler with no linker. Be aware that you still need the libraries and includes of gcc.

  NOTE: if you do use the GNU linker, you might need to change the `-G` flag to `-shared` in the `SOFLAGS` definition in your `include/makeinclude/platform_macros.GNU`.

- Don't get too confused about contradictory statements in the gcc documentation. It was written by different people...

- 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 the end of apps/Gateway/Gateway/Connection_Handler.cpp for one example. An easy way to figure out what template instantiations 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 -frepo option instead of -fno-implicit-templates. ACE readily this option for application code: to enable it just add `repo=1` to your `make` invocation, or to your `include/makeinclude/platform_macros.GNU`. ACE still uses explicit template instantiation for building its libraries to help avoid link conflicts. Please see the g++ FAQ and gcc manual for more information on the -frepo option.

- The implementation of templates for g++ version 2.8 eliminates the restriction against static data members in template classes.

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

- On VxWorks only, g++ (thru version 2.7.2, distributed with Tornado 1.0.1/VxWorks 5.3.1), for x86 targets, -fno-implicit-templates is broken. In addition, -O2 is not supported on some targets.

#### Compiling ACE with egcs

- ACE transparently supports egcs, for the most part. Please see Compiling ACE with g++ in this document. And, please use the appropriate g++ config and platform files for the OS on which you will use egcs.

- WARNING: The default behavior of the ACE Makefiles is to add `-fno-exceptions` to egcs (and g++ starting with version 2.8.0) invocations. This disables exception handling support. On Solaris/sparc and Linux/alpha, it results in a 25 percent reduction in the size of libACE.so. To enable exception handling, add `exceptions=1` to your `make` command line invocation, or to your `$ACE_ROOT/include/makeinclude/platform_macros.GNU`.

- egcs may have trouble linking some executables, such as the ACE IOStream_Test, if its static libraries are used. Though Tim Rose reports that egcs 1.1.1 static libraries work just fine on Solaris 2.6 with patches: 105181-12, 105568-13, 105210-19, 105591-05, 105395-04, and 105490-07.

  If you need or want to use egcs' shared libraries, build it with the `--enable-shared` egcs config option. The `--enable-shared` option is not an egcs run-time option. Build egcs in a way similar to the following example:

               $ ./configure --enable-shared
               $ make bootstrap

  Be sure to set your `LD_LIBRARY_PATH` environment variable, if necessary, to pick up those shared libraries.

- On DEC Alpha, egcs through version 1.03a, at least, may fail to build ACE if debugging (-g) is enabled. The fix is to edit the egcs gcc/mips-file.c file, at line 976, and change `PAGE_SIZE` to 8192. Then rebuild ACE. Thanks to Ganesh Pai for this information.

- Sun OS 5.6 using egcs1.1.2/egcs 2.95 with ld:Software Generation Utilities - Solaris/ELF (3.0) as: WorkShop Compilers 4.X dev 18 Sep 1996

  You could come across weird external symbol compiler errors. Example:

            -I/opt/ace/SunOS-1.0 -DACE_HAS_EXCEPTIONS  -o Cached_Accept_Conn_Test
            .obj/Cached_Accept_Conn_Test.o  -L/opt/ace/SunOS-1.0/ace -L./  -lACE
            -lsocket -ldl -lgen -lnsl -lposix4 -lthread
            ld: warning: relocation error: R_SPARC_32: file
           .obj/Cached_Accept_Conn_Test.o: symbol
             __t21ACE_Cache_Map_Manager7Zt30ACE_Refcounted_Hash_Recyclable1Z13
             ACE_INET_AddrZP18Client_Svc_HandlerZt23ACE_Hash_Map_Manager_Ex5Zt
            30ACE_Refcounted_Hash_Recyclable1Z13ACE_INET_AddrZt8ACE_Pair2ZP18
            Client_Svc_HandlerZUiZt8ACE_Hash1Zt30...

  external symbolic relocation against non-allocatable section .stab; cannot be processed at runtime: relocation ignored

  Solution:

  Install the "binutils" package from GNU (www.gnu.org); specifically, "as" and "ld".

  Conclusion:

  Perfect build stats:

  OS: Kernel version: SunOS 5.6 Generic 105181-03 December 1999.

  compiler: gcc version egcs-2.91.66 19990314 (egcs-1.1.2 release)

  loader: GNU ld version 2.9.1 (with BFD 2.9.1) Supported emulations: elf32_sparc

  assembler: GNU assembler version 2.9.1 (sparc-sun-solaris2.6), using BFD version 2.9.1

  Thanks to John Gathright for providing this information.

### Building and Installing ACE

The following explains how to build the ACE on UNIX and Win32.

#### General Rules

- Many features in ACE can be modified by defining some macros in `$ACE_ROOT/ace/config.h`. These macros should always appear before including your platform specific config file.

- However, if you want to undefine/redefine macros defined in the platform specific config file, these `#undef` should come after the config file.

#### Building and Installing ACE on UNIX

Building and installing ACE on UNIX is relatively simple (the process for Win32 is different). 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). You must use GNU make or ACE won't compile.

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. The ACE recursive Makefile scheme needs this information. There are several ways to set the ACE_ROOT variable. For instance, in my .login file I have the following entry:

             % setenv ACE_ROOT /home/cs/faculty/schmidt/ACE_wrappers

   However, if you're building a number of versions of ACE, e.g., for different OS platforms or for different releases of ACE, you might use the following approach:

             % setenv ACE_ROOT $cwd

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. Note, however that you can normally skip this step because the defaults are typically fine for most systems.

4. Create a `$ACE_ROOT/ace/config.h` file that includes 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). Make sure you settings are placed before the inclusion of the platform-specific header file.

   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 because ACE builds shared libraries, you'll need to set LD_LIBRARY_PATH to whereever you put the binary version of the ACE library. For example, you probably want to do something 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 ACE library, tests, the examples, and the sample applications. Building the entire ACE release can take a long time and consume lots of disk space, however. Therefore, you might consider cd'ing into the $ACE_ROOT/ace/ directory and running `make` there to build just the ACE library. As a sanity check, you might also want to build and run the automated ``one-button'' tests in $ACE_ROOT/tests/. Finally, if you're also planning on building TAO, you should build the gperf perfect hash function generator application in $ACE_ROOT/apps/gperf/.

8. If you need to regenerate the Svc_Conf_y.cpp file, you'll need to get Berkeley YACC. However, you should rarely, if ever, need to do this.

#### Building and Installing ACE on Win32

First, if you are upgrading from an older release, clean up everything and rebuild from scratch to ensure that everything is rebuilt correctly. You might have to manually go through the ACE directories and delete all *.obj, *.dll, *.lib, *.ilk, *.pdb, *.idb, *.ncb, *.opt, and *.exp files in order to start over from scratch (the Clean command in MSVC may not do this).

ACE contains project files for Microsoft Visual C++ 5.0 or later (*.dsw), Borland C++ 5.x (ace.ide), IBM's VisualAge C++ compiler (*.icc). There are also Makefile.bor files to compile ACE, the ACE one-button tests, and TAO with Borland C++ Builder 4.0.

The Borland C++ Builder 4.0 port has been done by Jody Hagins, so contact him for any questions.

Note concerning MSVC 5.0 and Service Pack 3: There has been confusion regarding MSVC 5 and its Service Pack 3. Some ACE users have, in the past, had problems with SP3 that were not present in SP2. Thanks to the diligent efforts of Bill Fulton, the mystery appears to be solved. The key? (Oh, this is a good one...) It would appear that there are actually multiple versions of SP3 in existence. The earlier ones have the bug, while later ones have it fixed. The service pack downloadable from Microsoft's web site as of June 16, 1998 works fine. The CD containing SP3, if it has part number X03-50158 on the disc (the part number on the jacket is probably different), also works fine.

So, if you are experiencing problems with SP3, get a newer one - it'll probably work. Sheesh...

We no longer actively support MSVC 4.x. ACE might work with the compiler but not without some work.

Note, however, that regardless of the version of SP3, there are some STL bugs in SP3 which you should get corrected. Please see http://www.dinkumware.com/vc_fixes.html for details. Thank you to Ben Eng for the pointer to the STL fixes.

1. Uncompress the ACE distribution into a directory, where it will create a ACE_wrappers directory containing the distribution. The ACE_wrappers directory will be referred to as ACE_ROOT in the following steps -- so ACE_ROOT\ace would be C:\ACE_wrappers\ace if you uncompressed into the root directory.
2. Create a file called `config.h` in the ACE_ROOT\ace directory that contains:
   `#include "ace/config-win32.h"`
3. Now load up the project file for ACE (ACE_ROOT\ace\ACE_Library.mdp or ACE_ROOT\ace\ace.dsw).
4. Each project will contain 8 different configurations. These are a mixture of Debug/Release, Unicode/non-Unicode, and Static/Dynamic library versions for both i386 and Alpha machines. Make sure you are building the one you'll use. All these different configurations are provided for your convenience. You can either adopt the scheme to build your applications with different configurations, or use `ace/config.h` to tweak with the default settings on NT. Note: If you use the dynamic libraries, make sure you include ACE_ROOT\bin in your PATH whenever you run programs that use ACE.
5. If you are building for Windows NT then you can start building now. If you are building on Windows 95, then you should add the line
   `#define ACE_HAS_WINNT4 0`
   before the #include statement in ACE_ROOT\ace\config.h and it will turn off Windows NT 4 specific code.
6. If you want to use the standard C++ headers (iostream, cstdio, ... as defined by the C++ Standard Draft 2) that comes with MSVC 5, then add the line
   `#define ACE_HAS_STANDARD_CPP_LIBRARY 1`
   before the #include statement in ACE_ROOT\ace\config.h.
7. To use ACE with MFC libraries, also add the following to your `config.h` file. Notice that if you want to spawn a new thread with CWinThread, make sure you spawn the thread with THR_USE_AFX flag set.
   `#define ACE_HAS_MFC 1`
   By default, all ACE examples use DLL version of run-time libraries regardless you are building DLL or static version of ACE. You can still choose to link ACE statically or dynamically regardless of run-time libraries. The reason of choosing to link run-time library dynamically is almost every NT box has these library installed and to save disk space. If you prefer to link MFC as a static library into ACE, you can do this by defining `ACE_USES_STATIC_MFC` in your `config.h` file. If you insist on linking everything statically, you'll have to modify the project file yourself.

8. Static version of ACE libraries are build with the following macros defined:
   `ACE_HAS_DLL=0`
   `ACE_NO_INLINE`
   You should also have them defined in you application projects if you want to use the default static ACE libraries with them.

9. If you are building for Windows CE, you need to add the line
   `#define ACE_HAS_WINCE`
   before including <ace/config-win32.h>. Notice that CE uses a different set of dsw/dsp files.
10. The default project files which build ACE library have various configurations to build dynamic/static, with or without Unicode support. Although we recommend using the dynamic library, if, for some reasons, you would rather work with static library, you'll need to add the line
    `#define ACE_HAS_DLL 0`
    before the #include statement in ACE_ROOT\ace\config.h. Optionally but highly recommended, you can also add the line
    `#define ACE_NO_INLINE`
    before the #include statement in ACE_ROOT\ace\config.h to disable inline function and reduce the size of static libraries (and your executables.) Notice that you need to use DLL version of run-time libraries even you are using ACE as a static library. That's the default behavior.
11. Barry Hoggard maintains a CORBA Page which contains very helpful information on setting MSVC project settings. You'll need to filter out stuff related to TAO if you only use ACE.

ACE TESTS

The tests are located in ACE_ROOT\tests. There are two corresponding project files in that directory also (tests.mdp and tests.dsp).

Once you build all the tests (Batch Build works well for this), you can run the batch file `run_tests.bat` in the `tests` directory to try all the tests.

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 Protocol: 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 Service: 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 ACE:
    Installed Software:
    Computer Browser
    MS Loopback Adapter Driver
    TCP/IP Protocol
    Workstation
    Installed Adapter Cards:
    MS Loopback Adapter

NT ALPHA CONFIGURATIONS

Many project files already contain Alpha NT configurations, but others do not (requiring them to be added). Also, since most of the development happens on x86, problems building ACE on Alpha NT can often be fixed by recreating the configurations from the x86 versions.

Here are the steps to add an Alpha Configuration.

1. Load the project on the Alpha machine.
2. Go to the Build menu and then Configurations.
3. Select the project that you want to convert.
4. Click on Add.
5. Select the x86 configuration to "Copy settings from" (either Debug or Release versions).
6. Prepend "Alpha " to the beginning of the name under "Configuration".
7. Click OK.
8. Close the "Configurations" window.
9. Now go to the Project settings.
10. For the General Settings, change the output directories to standard ACE output directores. Intermediate Directories are "Debug" and "Release" in most cases. The Output Directories are blank, except for Release versions of executables, in which it is also "Release".
11. For the C/C++ Settings, make sure that the Code Generation's runtime library is set to "Multithreaded DLL" or "Debug Multithreaded DLL".

Note: MSVC 6 has a bug where if a .dsp is converted from version 5 to 6 on x86, the Alpha configuration will be partially corrupted. If this occurs, the easiest way to fix it is as above, recreate it.

#### Building and Installing ACE on VxWorks

For the most part, you should be able to follow the instructions above to build ACE and applications that use it. Start with the Unix instructions above to build ACE and the applications that use it. Please see below for more information on building ACE on NT hosts for VxWorks targets.

A few notes on VxWorks builds (thanks to Paul von Behren for these notes):

- VxWorks builds are done with a cross compiler, i.e., the compiles are done on a workstation creating object modules which are downloaded and loaded into the VxWorks target system.

- C++ object modules must be post-processed by a VxWorks utility called ``munch.'' ACE includes a perl script called $ACE_ROOT/bin/ace_ld, which is called from the Makefiles, replacing the traditional `ld` step. You must have perl installed to use `ace_ld`. If perl is not on your path, you'll have to set `PERL_PATH` to the full path (including perl.exe), either in your `$(ACE_ROOT)/include/makeinclude/platform_macros.GNU` or in your environment.

- Wind River provides GCC/G++ cross-compilers for the supported target platforms. The executables are named cc<target> and g++<target>; for example, ccppc and g++cpp for PowerPC targets.

You'll have to let ACE know the target type at compile time. There are several ways to do this; please see the `$ACE_ROOT/include/makeinclude/platform_vxworks5.x_g++.GNU` platform file for detailed information.

The VxWorks platform_vxworks*.GNU files are set up so that shared libraries are not built on VxWorks, by default. Only static libraries, with .a extension, are built. Therefore, it's not necessary to set the LD_LIBRARY_PATH environment variable on your host system when building for VxWorks targets. Please note, however, if you use TAO on VxWorks that you will need to set your LD_LIBRARY_PATH to find the TAO IDL compiler libraries (installed in the ace directory) on the host.

With g++, $ACE_ROOT/bin/ace_ld is used to munch object files and libraries to set up calls to static constructors and destructors. bin/ace_ld requires perl on the host platform.

These non-default VxWorks kernel configuration `#defines` are required with ACE:

    #define INCLUDE_CPLUS           /* include C++ support */
    #define INCLUDE_CPLUS_IOSTREAMS /* include iostreams classes */
    #define INCLUDE_POSIX_ALL       /* include all available POSIX functions */

For completeness, here are the non-default `#defines` that we used for VxWorks 5.3.1/g++ 2.7.2:

    #define INCLUDE_CPLUS           /* include C++ support */
    #define INCLUDE_CPLUS_IOSTREAMS /* include iostreams classes */
    #define INCLUDE_CONFIGURATION_5_2 /* pre-tornado tools */
    #define INCLUDE_DEBUG           /* pre-tornado debugging */
    #define INCLUDE_LOADER          /* object module loading */
    #define INCLUDE_NET_SYM_TBL     /* load symbol table from network */
    #define INCLUDE_SYM_TBL_SYNC    /* synchronize host and target symbol tables */
    #define INCLUDE_NFS             /* nfs package */
    #define INCLUDE_PING            /* ping() utility */
    #define INCLUDE_POSIX_ALL       /* include all available POSIX functions */
    #define INCLUDE_RDB             /* remote debugging package */
    #define INCLUDE_RLOGIN          /* remote login */
    #define INCLUDE_RPC             /* rpc package */
    #define INCLUDE_SECURITY        /* shell security for network access */
    #define INCLUDE_SHELL           /* interactive c-expression interpreter */
    #define INCLUDE_SHOW_ROUTINES   /* show routines for system facilities*/
    #define INCLUDE_SPY             /* spyLib for task monitoring */
    #define INCLUDE_STARTUP_SCRIPT  /* execute start-up script */
    #define INCLUDE_STAT_SYM_TBL    /* create user-readable error status */
    #define INCLUDE_SYM_TBL         /* symbol table package */
    #define INCLUDE_UNLOADER        /* object module unloading */
    #define INCLUDE_WINDVIEW        /* WindView command server */

If you use TAO, it's also a good idea to increase the `NUM_FILES` parameter from its default of 50 to, say, 1000.

Please note that those VxWorks kernel configuration parameters are set in the VxWorks configAll.h file. You must rebuild your VxWorks kernel after modifying that file.

If you're first getting started with ACE and/or VxWorks, I recommend just building the ACE library and tests first. (Some of the ACE examples, in System_V_IPC, don't build on VxWorks yet.) Then try running the tests. Please see $ACE_ROOT/tests/README for the latest status of the ACE tests on VxWorks.

Please note that the `main` entry point is renamed to `ace_main` (configurable via ACE_MAIN) on VxWorks with g++, to comply with its restriction against using `main`. In addition, ACE_HAS_NONSTATIC_OBJECT_MANAGER is enabled by default to cleanly support construction and destruction of static objects. Please see the Non-static ACE_Object_Manager discussion for the important implication of this feature.

ACE threads (VxWorks tasks) can be named, for example, by supplying a non-null argument to the Thread_Manager spawn routines. However, names beginning with `"==ace_t=="` are forbidden because that prefix is used internally by ACE.

You can spawn a new task to run `ace_main`, using either VxWorks `sp`, or ACE'S `spa`. `spa` can be used from the VxWorks shell to pass arguments to `ace_main`. Its usage is:

    spa ace_main, "arg1" [, ...]

All arguments must be quoted, even numbers.

The ACE tests write their output files in a directory named `log/`, below the current (`tests`) directory. If you don't have NFS included in your VxWorks kernel, you can use these steps, provided by Clarence M. Weaver, to run the tests and capture their output:

1. What I did was create a log directory on the boot NT host of my vxworks target.

2. I copied all the test applications and the run_tests.vxworks script to the parent of the log directory.

3. Using the target shell not the host shell, I "cd" to the directory containing the script and test programs.

4. Invoked the script < run_tests.vxworks from this target shell.

Kirk Davies provided this approach for running the ACE tests on Tornado II:

- Under Tornado II, I set up the Target Server File System (TSFS), and the test logs get written to the log subdirectory under that.

- You have to set an environment variable before running the tests:

      putenv("ACE_TEST_DIR=/tgtsvr")

##### Building Shared Libraries for VxWorks.

ACE supports shared libraries for VxWorks, but only with the g++ compiler. To build shared libraries instead of the default static libraries, added `shared_libs_only=1` to either your `ACE_wrappers/include/makeinclude/platform_macros.GNU` or your `make` invocation. Then, be sure to load the ACE (and any other) shared library before loading your executable(s).

A shared library for VxWorks uses the same code as for a static (non-shared) library. However, calls to static constructors/ destructors are added. The code in the shared library must be reentrant if you shared it between programs (tasks). The ACE library meets this requirement.

Shared libraries reduce build time, executable size, and load time of the executable. But, you must manually load the shared library before loading your executable(s) with a command such as:

    -> ld < libACE.so

Shared libraries can be unloaded the same way an executable (module) is unloaded.

NOTE: Shared libraries on VxWorks aren't the same as shared libraries on other operating systems. In particular, there is no support for creating copies of writeable global (static) data in the shared library. This includes the singleton ACE_Object_Manager instance pointer. If you share global data between separate programs, they may not work properly. See the discussion of shared code and reentrancy in the VxWorks' Programmers Guide.

Instead of trying to run separate programs onto a VxWorks target, we recommend creating just one program, and spawning a thread for each task. The TAO IDL_Cubit test collocation test is a good example.

##### Linking ACE and/or TAO Libraries into the VxWorks Kernel.

It's easy to link your ACE and/or TAO libraries into the VxWorks kernel. Just build shared versions, but disable the munch step. The easiest way to do that is to set the `LD` make variable to the name of your linker. For example, to build a libACE.so for PowerPC that can be linked into the kernel:

    % cd $ACE_ROOT/ace
    % make LD=ldppc shared_libs_only=1

After building the shared lib, link it into the kernel by setting the `MACH_EXTRA` make variable in the kernel configuration Makefile. Then, build the kernel using `make exe`.

##### Building ACE on Tornado/NT hosts for VxWorks targets.

The following, very useful information was contributed by Chris Ryan and Paul von Behren. Please submit corrections, additions, or clarifications to the the ACE mailing list.

NOTE:The make (version 3.74) that is provided with Tornado II cannot be used to build ACE. Use Cygnus' make (version 3.75) instead.)

NOTE:Optimization is enabled be default in platform_vxworks5.x_g++.GNU. However, the compiler that is shipped with Tornado II has trouble compiling some files with -O2. To disable optimization for an individual file, just add `optimize=0` to your make invocation when compiling that file.

Using the Cygnus tools, this approach works:

- You'll build both your NT and VxWorks executables in the same workspace (directory hierarchy). This works because the NT compiler and ACE's Makefiles put their output in different directories.

- Set up your `ACE_wrappers/include/makeinclude/platform_macros.GNU` as usual for VxWorks. See the g++/VxWorks platform file for more information.

- Create an `ACE_wrappers/ace/config.h` file that looks something like the following. tao_idl should be built to not support native exception handling, because that's not available on VxWorks.

      #if defined (_MSC_VER)  ||  defined (__BORLANDC__)
      # include "ace/config-win32.h"
      # undef ACE_HAS_EXCEPTIONS
      #else
      # include "ace/config-vxworks.h"
      #endif

- Set your `ACE_ROOT`, `CPP_LOCATION`, `WIND_BASE`, and `WIND_HOST_TYPE` environment variables.

- Build for NT, then build for VxWorks.

A few additional Windows Notes, from Paul von Behren:

- Cygnus has created a Win32 API which is compatible with a ``generic'' Unix environment. Using this library, they have ported a large collection of GNU tools to WinNT/95 - including a port of gcc/g++. See http://www.cygnus.com/misc/gnu-win32/ A related link is ftp://ftp.cygnus.com/pub/gnu-win32/latest/

- To set up the command-prompt build environemnt, run `Tornado\host\x86-win32\bin\TorVars.bat`. This is done implicitly within the Tornado IDE.

- To run `ace_ld`, you still need perl installed - see http://www.activestate.com/software/default.htm for Windows perl.

- The Tornado IDE will use a standard Makefile for project builds, but does not have a GUI interface for managing the Makefile. By default, it will use rules from Makefile in the current directory and you can configure it to add certain Makefile targets to the project. If you have `ACE_ROOT` defined before starting Tornado, you can specify an ACE Makefile as a Tornado target and Tornado will then call make from the menu.

And Chris Ryan's instructions for building for VxWorks targets on Windows NT hosts:

1. Path setting that seems to be working is:

             /tornado/host/x86-win32/bin:
             /tornado/host/x86-win32/lib/gcc-lib/i386-wrs-vxworks/cygnus-2.7.2-960126:
             /tornado/host/x86-win32/i386-wrs-vxworks/bin:
             /ace/ace_wrappers/bin:
             /gnuwin32/b18/H-i386-cygwin32/bin:
             /gnuwin32/b18/tcl/bin:
             /WINNT/system32:
             /WINNT:
             /WINNT/system32/nls/ENGLISH:
             /bin

   Other environment variables:

             WIND_BASE=/tornado
             SHELL=/bin/sh.exe
             TERM=pcbios
             TAO_ROOT=/ace/ACE_wrappers.vxworks/TAO
             CPP_LOCATION=/Program Files/DevStudio/VC/bin/CL.EXE
             GCC_EXEC_PREFIX=/tornado/host/x86-win32/lib/gcc-lib/
             WIND_HOST_TYPE=x86-win32
             ACE_ROOT=/ace/ACE_wrappers.vxworks

2. `/tornado` is the root of the Tornado install (`$WIND_BASE`).
3. `/gnuwin32` is the root of a Cygnus GNU download and install.
4. `/bin` content is:

             aced.dll
             cygwin.dll
             perl.exe
             rm.exe
             sh.exe
             true

   `aced.dll` is produced in an ACE NT source tree according to documented procedure for NT VC++5.0 ACE build. `cygwin.dll` is from the Cygnus GNU software download and install.
5. Basically, follow documented procedure for ACE build/install on UNIX platform. Create a `$ACE_ROOT/ace/config.h` that looks like:

             #include "config-vxworks5.x.h"

   And create a `$ACE_ROOT/include/makeinclude/platform_macros.GNU` that looks like:

             WIND_BASE = /tornado
             WIND_HOST_TYPE = x86-win32
             CPU = I80486
             include $(ACE_ROOT)/include/makeinclude/platform_vxworks5.x_g++.GNU

##### TAO on NT Tornado host, VxWorks target.

1. Build ACE and TAO_IDL in the NT tree as already documented. As mentioned above, I put `aced.dll` in `/bin`. Be sure to build ACE's gperf on NT, in `ACE_wrappers/apps/gperf/src`.

2. Build $TAO_ROOT/tao

             CPP_LOCATION=/Program Files/DevStudio/VC/bin/CL.exe
             cd $TAO_ROOT/tao
             /gnuwin32/b18/H-i386-cygwin32/bin/make

3. Build orbsvcs.

             CPP_LOCATION=/Program Files/DevStudio/VC/bin/CL.exe
             cd $TAO_ROOT/orbsvcs/orbsvcs
             /gnuwin32/b18/H-i386-cygwin32/bin/make

4. Build $TAO_ROOT/tests

### Building and Installing ACE Network Services

The following explains how to build the ACE network services on UNIX and Win32.

#### Building and Installing ACE Network Services on UNIX

Building and installing ACE Network Services on UNIX is relatively simple (the process for Win32 is different). Here's what you need to do:

1. Build and install ACE on UNIX as described earlier. If ACE is built at the root of the ACE source tree (and ACE has been ported to your platform, of course) the netsvcs static and shared object libraries should be built automatically. In addition, the server driver program (`main`) contained in $ACE_ROOT/netsvcs/servers/main.cpp should also be compiled and ready to run.

2. Set your LD_LIBRARY_PATH environment variable to where the binary version of the ACE netsvcs library. For example, you probably want to do something like the following

             % setenv LD_LIBRARY_PATH $ACE_ROOT/ace:$LD_LIBRARY_PATH

3. By default, if the shared object library is built, the services are linked into the `main` driver program dynamically. To specify which services should be linked in and executed, edit the $ACE_ROOT/netsvcs/servers/svc.conf file. During your editing, you should update information (such as the default service port numbers) that affects the initialization of services in this file. Refer to the Service Configurator documentation to learn how the configuration file is parsed and how the services are dynamically linked and executed. In addition, refer to the Network Services documentation to learn more about how to configure each network service.

4. If you only want to link the services statically, simply remove or rename the svc.conf file.

#### Building and Installing ACE Network Services on Win32

Once again, there are supplied project for MSVC 5.0 or later for the Network Services.

### What Do I Need to Build for TAO?

Toshio Hori <toshi@etl.go.jp> provided these suggestions on building just what's needed for (a subset of) TAO:

I usually make:

        $ACE_ROOT/ace,
        $ACE_ROOT/apps/gperf,
        $TAO_ROOT/tao,
        $TAO_ROOT/TAO_IDL, and
        $TAO_ROOT/orbsvcs/orbsvcs

and the whole make takes less than an hour on my Solaris 7 for intel, Pentium-III/550MHz, 256MB memory, 512MB swap machine. (Top secret: I renice the 'make' process to the highest priority, -20... ;-) To save time and space, I set

        TAO_ORBSVCS = Naming Time Trader ImplRepo

in $ACE_ROOT/include/makeinclude/platform_macros.GNU also. See TAO's orbsvcs library customization instructions for more information.

### System Resource Requirements

The amount of system resources required to build ACE and TAO varies greatly. Platform, build options, and components built primarily influence the required system resources. As a rough guide, the typical peak memory requirement could be well over 256 Mb (notably, for TAO's orbsvcs). An entire build of ACE and TAO can use well over 1300 Mb of disk space. It's usually not necessary to build all of ACE and TAO, though.

Much less disk space is required for just the libraries. For example, see the ACE library subset sizes.

If you run out of memory when building, you might consider trying some or all of these suggestions:

- Enable or increase virtual memory. If you're on a Linux or LynxOS platform, please see the appropriate sections above.

- Disable/enable optimization and/or debugging. See the Makefile Flags discussion for information on how to do that via ACE's Makefiles.

- If you're using g++, try removing `-pipe` from `CFLAGS` in your `include/makeinclude/platform_macros.GNU` file.

- Restrict the components that you build. For ACE and TAO, see the discussion of `ACE_COMPONENTS` in the ACE subsets page. For TAO's orbsvcs, see the discussion of `TAO_ORBSVCS` in orbsvcs Library configuration information.

  If disk space is a problem, disabling debugging should greatly reduce object code, and therefore, library size. This is especially true with g++.

  Toshio Hori <toshi@etl.go.jp> provided these tips for reducing disk space usage:

  To save space on a Unix machine, I usually run find . -name \*.dsw -o -name \*.dsp -o -name \*.bor | xargs rm -f in $ACE_ROOT at first after untar the distribution. They are meaningless in my environment.

  Finally, to save space, may want to run 'make clean' after 'make'. It removes generated object files and leaves libraries/exectables intact.

### Advanced Topics

- Porting ACE and TAO to a New OS Platform
- Using GNU's Autoconf with ACE
- Non-static ACE_Object_Manager
- Cloning the Source Tree
- Building CORBA Versions of ACE
- Additional Build Tips for MVS
- Makfile Flags
- Version Control
- ACE Makefile hints
- ACE SSL effort

#### Non-static ACE_Object_Manager

The ACE_Object_Manager can be instantiated as a static object, can be instantiated on the stack of the main program thread, or can be explicitly instantiated and destroyed by the application with `ACE::init ()` and `ACE::fini ()`. The comments in the header file, `ace/Object_Manager.h` provide more detail.

NOTE: Special requirements are imposed on applications if the ACE_Object_Manager is instantiated, by ACE, on the stack of the main thread. This behavior is selected by defining `ACE_HAS_NONSTATIC_OBJECT_MANAGER` in `ace/config.h`. Again, see the ACE Object_Manager header file, `ace/Object_Manager.h` for more information. One of these requirements is discussed here, because it is so important. Please note that `ACE_HAS_NONSTATIC_OBJECT_MANAGER` is defined in the distributed ACE `config.h` headers for VxWorks and Win32.

The important requirement is that the program must declare its `main` function with two arguments, even if they're not used, and with `int` return type:

    int
    main (int, char *[])

If you don't declare `main` exactly that way, then you'll see a link error about `ace_main_i` being undefined.

Alternatively, this feature can be disabled by commenting out the #define ACE_HAS_NONSTATIC_OBJECT_MANAGER in the `ace/config.h`. But, that will make repeated testing more difficult on VxWorks. And, you'd either have to call static constructors and destructors manually or unload/load the program between runs. On Win32, disabling the feature can possibly lead to shutdown difficulties.

WARNING: `ACE_HAS_NONSTATIC_OBJECT_MANAGER` assumes that your `main` function is named `main`. Any violation of this assumption is at your peril. If you really need to call your entry point something other than `main`, you'll need to construct and destroy the ACE_Object_Manager. The best way to do that is to call `ACE::init ()` and `ACE::fini ()`. Or, see the `#define` of `main (int, char *[])` in `ace/OS.h` to see how ACE does that for entry points named `main`.

#### Cloning the Source Tree

On UNIX platforms, 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
    % (cd ace; echo "\#include "ace/config-sunos5.5-g++.h" > config.h)
    % (cd include/makeincludes; ln -s platform_sunos5-g++.h platform_macros.GNU)
    % setenv ACE_ROOT $cwd
    % make

This will establish a complete tree of links. Note that you must build a config.h and platform_macros.GNU in cloned directory. In addition, make sure you set your LD_LIBRARY_PATH to $ACE_ROOT/ace:$LD_LIBRARY_PATH on SVR4 UNIX platforms.

When you do a make in the $ACE_ROOT 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.

Alternatively, the perl script `ACE_wrappers/bin/create_ace_build` can be used to create build trees. It creates them below `ACE_wrappers/build`. It filters out all but the necessary files, so the warning above does not apply. See the comments at the top of the script itself for usage information.

#### Building CORBA Versions of ACE

Note that if you are compiling with IONA's Orbix implementation of CORBA or Visigenix's implementation of CORBA, 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 up $ACE_ROOT/include/makeinclude/platform_macros.GNU and $ACE_ROOT/ace/config.h to use the config* and platform* files that have "-orbix" in them!

#### Additional Build Tips for MVS

For all intents and purpose, MVS OpenEdition (OE) is another flavor of UNIX, therefore, the instructions under Building and Installing ACE on Unix can be used along with the following additional tips:

You can get a copy of GNU make that has been ported to MVS OpenEdition from the IBM OpenEdition web site. ACE's make scheme generates compile commands that have options and operands interspersed. By default, the c89/cc/c++ compiler expects all options to precede all operands. To get around this, you must set a special compiler environment variable (_CXX_CCMODE) to 1 which tells the compiler to allow options and operands to be interspersed.

Note that the environment variable LD_LIBRARY_PATH is called LIBPATH on MVS.

Shared objects are built a little different on MVS than on other UNIX implementations. This has been accounted for in the makefiles that come with ACE When the linker (via the cxx command) builds the libACE.so file it will also create a file called libACE.x. This is a side-deck file and it must be included in subsequent link edits with application code. For more information on this see the C/C++ MVS Programming Guide. If you want to build your application statically, i.e., using libACE.a instead of libACE.so, you can set ACELIB to ACELIB_STATIC in platform_mvs.GNU.

When the libACE.so file is built (via the MVS pre-linker and binder), you will get a rc=4 from the pre-linker. This is ok. This is due to some warnings about unresolved references which should get resolved during the link step. Note, however, there shouldn't be any unresolved references from the binder (linkage editor). You can get pre-link and link maps by uncommenting the PMAP and LMAP lines in the platform_mvs.GNU file.

#### Makefile Flags

ACE supports the following flags. They can be enabled either on the command line, e.g., "make purify=1", or added to your platform_macros.GNU. To disable the option, set the flag to null, e.g., "make debug=". Some flags support setting to 0 disable, e.g., "make debug=0". debug=1 is enabled in the platform files that are released with ACE.

Please note that the effects of a flag may be platform specific. Also, combinations of certain flags may or may not be allowed on specific platforms, e.g., debug=1 opt=1 is supported by g++ but not all other C++ compilers.

If you use Purify or Quantify: purify or quantify must be on your `PATH`. By default, ACE puts the Purify/Quantify caches below `/tmp`. To override that, set the `PURE_CACHE_BASE_DIR` variable, either in your environment or on the `make` make command line, to the destination directory for your instrumented libraries.

    Flag             Description
    ----             -----------
    debug            Enable debugging; see DCFLAGS and DCCFLAGS.
    exceptions       Enable exception handling (not supported by all platforms).
    fast             Enable -fast option, e.g., with Sun C++.
    inline           Enable ACE inlining.  Some platforms enable inlining by
    default, others do not.
    optimize         Enable optimization; see OCFLAGS and OCCFLAGS.
    orbix            Enable use of Orbix.
    probe            Enable ACE_Timeprobes.
    profile          Enable profiling; see PCFLAGS and PCCFLAGS.
    purify           Purify all executables.
    quantify         Quantify all executables.
    repo             Use GNU template repository (g++ with repo patches and
                       egcs only).
    rtti             Enable run-time type identification.  On some platforms,
                       it is enabled by default, so this is ignored.
    shared_libs      Build shared libraries. Ignored if static_libs_only is set.
    static_libs      Build shared libraries. Ignored if shared_libs_only is set.
    shared_libs_only Only build shared libraries.  Ignored if no SHLIBs are
    specified by the Makefile, as in performance-tests/Misc.
    static_libs_only Only build static libraries.
    threads          Build with thread support.
    xt_reactor       Build the XtReactor.

    Usually, users do not need to be concerned with make targets.
    Just enter ``make'' on the command line to build.  A few notable
    targets are listed below.

    Target             Description
    ------             -----------
    show_statics       Lists all static objects in object files built for
    current directory.  Only supported for g++.
    show_uninit        Lists all uninitialized in object files built for
    current directory.  Only supported for g++.

Back to the ACE home page.