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.

Document Index

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 (MSVC++ 4.x, 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), Chorus
Partially supported, i.e., infrequently tested Windows CE, Tandem, SCO, UnixWare, SunOS 4.x, FreeBSD, NetBSD
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

Compiling ACE with GNU g++

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

Compiling ACE with egcs

Building and Installing ACE

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

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 since 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, 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/.

  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++ 4.x (*.mdp) and 5.0 with Service Pack 3, and 6.0 (*.dsw), as well as Borland C++ 5.x (ace.ide).

There are also project group files (BPG) to compile ACE and the one-button tests with Borland C++ Builder 3.0. This port has not been completed yet, so basically you are on your own here. The port was started by Gonzalo A. Diethelm, so contact him for any further directions.

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

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. 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. If ACE will be used with MFC programs, 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. 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.

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

  10. 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 mroe information on building ACE on NT hosts for VxWorks targets.

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

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

It probably wouldn't take much effort to modify the ACE library to not require INCLUDE_CPLUS_IOSTREAMS, if necessary.

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.

By default, the ACE Makefiles link the ACE library into every executable. If you want to run multiple ACE executables but just use a single ACE library, it should be possible, though I haven't tried it. Just link the first executable to be loaded onto the target with the ACE library, as usual. All other executables can be linked without the ACE library by added ACELIB= to the make invocation when building them. When they are loaded onto the target, the should load against the symbols from the ACE library from the first executable that was loaded.

Building Shared Libraries for VxWorks.
ACE now supports shared libraries for VxWorks, but only with the g++ compiler. To build shared libraries instead of the default static libraries, added static_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.

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.

A few additional Windows Notes, from Paul von Behren:

And Chris Ryan's instructions for building for VxWorks targets on Windows NT hosts:
  1. Create UNIX-like environment in NT Command Prompt windows by downloading GNU bash, perl, and so forth from your favorite ftp site. I went to ftp://ftp.cygnus.com/pub/gnu-win32/latest/ and downloaded cdk.exe and installed that on my NT box. I downloaded perl5.0 from where I can't remember. There may have been bits and pieces from other places for things like vi and less.
  2. Download latest ACE. Create 2 parallel trees, say /ace/ACE_wrappers.NT and /ace/ACE_wrappers.vxworks. The NT tree is for building aced.dll and tao_idl.exe as currently documented for ACE/TAO on NT/VC++5.0. The VxWorks tree is the cross compilation tree.
  3. 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
  4. /tornado is the root of the Tornado install ($WIND_BASE).
  5. /gnuwin32 is the root of a Cygnus GNU download and install.
  6. /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.
  7. Basically, follow documented procedure for ACE build/install on UNIX platform. Create a $ACE_ROOT/ace/config.h that looks like:

          #define __ACE_INLINE__ 0
      #define ACE_HAS_DLL 0
      #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
      PATH += :$(WIND_BASE)/host/$(WIND_HOST_TYPE)/bin
      CPU = I80486
      include $(ACE_ROOT)/include/makeinclude/platform_NTvxworks5.x_g++.GNU
    (But, I guess the PATH+= line is superfluous based on the PATH as shown previously). Finally, create a $ACE_ROOT/include/makeinclude/platform_NTvxworks5.x_g++.GNU with diff output from 'diff platform_vxworks5.x_g++.GNU platform_NTvxworks5.x_g++.GNU' that looks like: 
          58c58
      < HOST_DIR        = $(WIND_BASE)/host/sun4-solaris2
      ---
      > HOST_DIR        = $(WIND_BASE)/host/x86-win32
      62,63c62,63
      < CXX             = g++$(TOOLENV)
      < CFLAGS          += -DVXWORKS -D_REENTRANT -ansi -fno-builtin
      -fno-defer-pop -fvolatile -nostdinc -nostdlib -pipe -Wall
      ---
      > CXX             = $(CC)
      > CFLAGS          += -DVXWORKS -D_REENTRANT -ansi -fno-builtin -fno-defer-pop \
      -fvolatile -nostdinc -nostdlib -Wall #-pipe
  8. Now, follow the existing documentation for a UNIX platform build of ACE such as: 
          cd $ACE_ROOT/ace; make
  9. To build $ACE_ROOT/tests, I had to use the make.exe in the /gnuwin32/b18/H-i386-cygwin32/bin directory as I couldn't get make shipped with Tornado to run ace_ld and I couldn't figure out any other work around.

          cd $ACE_ROOT/tests; /gnuwin32/b18/H-i386-cygwin32/bin/make
    Also, running the tests works as already documented.
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.
  2. Copy TAO_IDL/tao_idl.exe to TAO_IDL directory in the ACE/TAO vxworks source tree. (I didn't spend any time yet looking for the place where the makefiles are using the absolute path to tao_idl.exe.)
  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/tao 
          CPP_LOCATION=/Program Files/DevStudio/VC/bin/CL.exe
      cd $TAO_ROOT/tao
      /gnuwin32/b18/H-i386-cygwin32/bin/make
  5. 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 both MSVC 4.x and 5.0 for the Network Services.

If you are using MSVC 4.x, you will need to add another directory to your global include and library paths, ACE_ROOT/netsvcs/lib. When you use the dynamic libraries, make sure to also include ACE_ROOT/netsvcs/lib in your PATH.

Advanced Topics

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.