Using the Traditional ACE/GNU Configuration

Here's what you need to do to build ACE using GNU Make and ACE's traditional per-platform configuration method:

1. Install GNU make 3.79.1 or greater on your system (available via anonymous ftp from prep.ai.mit.edu in the pub/gnu/make/ 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 for TSCH/CSH I have the following entry:

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

   BTW, if you're running BASH or Bourne Shell you'll need to do the following:

   
         % ACE_ROOT=/home/cs/faculty/schmidt/ACE_wrappers; export ACE_ROOT
         

   If you're building a number of versions of ACE, however, (e.g., for different OS platforms or for different releases of ACE) you might use the following approach (again assuming TCSH/CSH):

   
         % 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 configuration file, $ACE_ROOT/ace/config.h, that includes the appropriate platform/compiler-specific header configurations from the ACE source directory. For example:

   
   #include "ace/config-sunos5-sunc++-4.x.h"
   

   The platform/compiler-specific configuration file contains the #defines that are used throughout ACE to indicate which features your system supports. See the $ACE_ROOT/ace/README file for a description of these macro settings. If you desire to add some site-specific or build-specific changes, you can add them to your config.h file; place them 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. Create a build configuration file, $ACE_ROOT/include/makeinclude/platform_macros.GNU, that contains the appropriate platform/compiler-specific Makefile configurations, e.g.,

   
   include $(ACE_ROOT)/include/makeinclude/platform_sunos5_sunc++.GNU
   

   This file contains the compiler and Makefile directives that are platform/compiler-specific. If you'd like to add make options, you can add them before including the paltform-specific configuration.

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:$ACE_ROOT/lib:$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 Windows

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

Building and Installing ACE on Windows with Borland C++

1. Uncompress the ACE distribution into a directory, where it will create an ACE_wrappers directory containing the source. 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"
   
   If you are building for Windows NT 4, Windows 2000, or Windows XP, then you can start without any more changes. If you are building on Windows 9x/Me, 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 some WinNT/Win2K-specific code in ACE.
   
   
3. Open a Command Prompt (DOS Box).
   
   
4. Set the ACE_ROOT environment variable to point to the ACE_wrappers directory. For example:
   
   set ACE_ROOT=C:\ACE_wrappers
   
   
5. Set the BCBVER environment vairable to the main version of your Borland C++ compiler. Currently 4, 5, and 6 are supported. For example:
   
   set BCBVER=5
   
   
6. Change to the ACE_ROOT\ace directory.
   
   
7. Build release DLLs for ACE by going:
   
   make -f Makefile.bor
   
   
8. You can build several different versions of ACE by setting environment variables before you run make:
   
   Set the environment variable below to build a debug version of ACE
   set DEBUG=1
   
   Set the environment variable below to build a static version of ACE
   set STATIC=1
   
   Set the environment variable below to build a unicode version of ACE
   set UNICODE=1
   
   Set the environment variable below to build a version of ACE with Codeguard support. Should only be used when DEBUG is also set
   set CODEGUARD=1
   
   Set the environment variable below to build a version of ACE that is build against the VCL-compatible run-time library. This can only be used with BCB version 4
   set PASCAL=1
   
   Set the environment variable below to build a version of ACE using the C++BuilderX preview compiler. This compiler isn't supported at this moment but by setting this environment variable the new compiler is used and you can expirement with this compiler.
   set CBX=1
   
   You can then start the build with the command
   make -f Makefile.bor
   
   You may also enable the options by passing them as command line options to make, for example:
   make -f Makefile.bor -DDEBUG -DPASCAL
   
   
9. Optionally install the ACE header files, libraries and executables for use in your applications. Here we are installing them into C:\ACETAO:
   
   make -f Makefile.bor -DINSTALL_DIR=C:\ACETAO install
   
   

If you are using C++Builder 4, then the libraries built using the above instructions are intended for use with generic console or windows applications and they link against the corresponding C++ runtime library. VCL applications created using BCB4's RAD environment must link against the VCL-compatible (ie pascal-compatible) runtime library. To tell the difference between these libraries the VCL-compatible ones have a 'p' in the suffix (i.e., 'p' for pascal). To build VCL compatible libraries try

set PASCAL=1
make -f Makefile.bor

The Borland C++ Builder 4.0/5.0/6.0 port has been done by Jody Hagins, Christopher Kohlhoff and Johnny Willemsen.

ACE TESTS

The tests are located in ACE_ROOT\tests. You build the tests using the Makefile.bor file, that is:

make -f Makefile.bor

Once you build all the tests, you can run the perl script:

run_test.pl -ExeSubDir Dynamic\Release

in the tests directory to try all the tests. You need to make sure the ACE bin directory (in this case ACE_ROOT\bin\Dynamic\Release) is on the path before you try to run the tests.

Building and Installing ACE on Windows with Microsoft Visual C++

Right now there is a SP4 (and hopefully only one of them) which fixes a deadlock problem in the STL.

We no longer actively support MSVC++ 5.x or earlier. ACE might work with these compilers but probably not without a bit of effort.

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.dsw).
   
   
4. Each project will contain several different configurations. These are a mixture of Debug/Release, MFC/Non-MFC, and Static/Dynamic library versions. Make sure you are building the one you'll use (for example, the debug tests need the debug version of ACE, and so on). 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 uses ACE. Otherwise you may experience problems finding ace.dll or aced.dll.
   
   
5. If you are building for Windows NT 4 or later (Windows 2000, XP, etc.) then you can start building without anymore changes. If you are building on Windows 9x/Me, 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 some WinNT/Win2K-specific code in ACE.
   
   
6. If you want to use the standard C++ headers (iostream, cstdio, ... as defined by the C++ Standard Draft 2) that comes with MSVC, 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 of the ACE projects use the DLL versions of the MSVC run-time libraries. You can still choose use the static (LIB) versions of ACE libraries regardless of run-time libraries. The reason we chose to link only the dynamic run-time library is that 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. However, if you would like to link everything (including the MSVC run-time libraries) statically, you'll need to modify the project files in ACE yourself.

8. Static version of ACE libraries are build with ACE_AS_STATIC_LIBS
   defined. This macro should also be used in application projects that link to static ACE libraries
   
   Optionally 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.)
   
   
9. ACE DLL and LIB naming scheme:
   
   We use the following rules to name the DLL and LIB files in ACE when using MSVC.
   
   "Library/DLL name" + (Is static library ? "s" : "") + (Is Debugging enable ? "d" : "") + {".dll"|".lib"}
   
   

More information for ACE/TAO on MSVC can be found here. The doxygen version of this document is available under Related Topics in the ACE Library.

The tests are located in ACE_ROOT\tests. There is also a workspace in that directory to build all the tests (tests.dsw)

Once you build all the tests (Batch Build works well for this), you can run perl script run_test.pl 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

Building and Installing ACE on Win32 with MinGW

If you are building for a machine without a network card, you may want to check here first.

Building and installing ACE on MinGW uses a mix of a UNIX building process and Win32 configuration files. Also, as MinGW uses GNU g++, you may want to take a look at the Compiling ACE with GNU g++ section.

You will need the MinGW build tools and libraries, downloable from http://www.mingw.org. For our build we required the following packages:

gcc, binutils, ld, libbfd, mingw-runtime, w32api.

You will also need GNU make for Win32 and the set of UNIX tools that the ACE UNIX build system uses (this include but is not limited to sh, rm, cp). For this purpose you can grab the Cygwin distribution from http://cygwin.com.

Be careful, because Cygwin includes it's own version of the compiler and build tools, you will need to have the MinGW build tools before the Cygwin set on you PATH environment variable (more on this later). The steps we followed in the build are:

1. Install Cygwin (this can be easy downloading and running setup.exe from the Cygwin site).
   
   
2. Install the MinGW tools. Download all the needed packages (see above) and unpack them on the same base directory, say c:/mingw32. If some of the packages are distributed on .tar.gz format, you may need to use the Cygwin version of the tar utility.
   
   
3. Open a Cygwin shell. Set your PATH environment variable so your MinGW's bin directory is first:

          % export PATH=//c/mingw32/bin:$PATH
          

   Note Cygwin uses ``/'' as directory separator, and ``//X'' as a notation for Win32 drive X. Note also that you can't use ``c:/mingw32/bin'' because, for Cygwin, ``:'' is path separator character, as in UNIX.
   
   

4. Add an ACE_ROOT environment variable pointing to the root of your ACE wrappers source tree:

          % export ACE_ROOT=c:/work/mingw/ACE_wrappers
          

   Note here you can't use the ``//X'' Cygwin notation as this is seen by MinGW's compiler and it doesn't support that (it does support ``/'' as directory separator however).

   From now on, we will refer to the root directory of the ACE source tree as $ACE_ROOT.
   
   

5. Create a file called config.h in the $ACE_ROOT/ace directory that contains:

          #include "ace/config-win32.h"
          

   If you are building for Windows 9X/Me (ie, not WinNT or Win2K), you will need to add:

          #define ACE_HAS_WINNT4 0
          

   before the #include line. Also, if you don't have Winsock 2 (check the SYSTEM and/or SYSTEM32 subdirectories of the windows instalation directory for ws2_32.dll), you will need

          #define ACE_HAS_WINSOCK2 0
          

   before the #include line. On NT 4, Windows 98 and later versions, you surely have Winsock 2. In Windows 95, including OSR2, you may don't have it if it wasn't specially installed. You may download it from the microsoft site. This is recommended as much ACE functionality depends on Winsock 2, and ACE without Winsock 2 support is tested very infrequently.
   
   
6. Create a file called platform_macros.GNU in the $ACE_ROOT/include/makeinclude directory containing:

          include $(ACE_ROOT)/include/makeinclude/platform_mingw32.GNU
          

   In the above text, don't replace $(ACE_ROOT) with the actual directory, GNU make will take the value from the environment variable you defined previously. If you lack Winsock 2, add the line

          winsock2 = 0
          

   before the previous one.
   
   
7. On the Cygwin shell, change to the $ACE_ROOT/ace directory and run make:

          % cd $ACE_ROOT/ace
          % make
          

   This should create libACE.dll (the Win32 shared library) and libACE.dll.a (the Win32 import library for the DLL). Note the name for the ACE DLL on MinGW follows the MinGW convention, that resembles UNIX.
   
   

   If you want static libs also, you may run:

          % make static_libs=1
          

8. The same rules for Win32 search of DLLs apply for MinGW. If you want to run some ACE programs from the Cygwin shell, you may need to add the directory for libACE.dll to your PATH:

          # export PATH=//c/work/mingw/ACE_wrappers/ace:$PATH
          

   If you are using MPC generated Makefiles, then the DLLs have been placed in the lib directory instead of ace and thus your PATH addition would need to look like this:

          # export PATH=//c/work/mingw/ACE_wrappers/lib:$PATH
          

If you are using ACE as a DLL, you will need to modify your PATH variable as explained above.

You may want to check $ACE_ROOT/tests/README for the status of the various tests on MinGW and the different Windows flavors.

Building and Installing ACE on Win32 with Cygwin

If you are building for a machine without a network card, you may want to check here first.

Building and installing ACE on Cygwin uses the UNIX building process. Also, as Cygwin uses GNU g++, you may want to take a look at the Compiling ACE with GNU g++ section.

You will need the Cygwin build tools and libraries, downloable from http://www.cygwin.com. For our build we require the following packages besides the packages the setup selects by default:

gcc (version 3.2.3), cygipc, make, perl.

1. Install Cygwin (this can be easy downloading and running setup.exe from the Cygwin site). For working with ACE we recommend to select DOS as default text file type.
   
   
2. Open a Cygwin shell. Set your PATH environment variable so your CYgwin bin directory is first:

          % export PATH=//c/cygwin/bin:$PATH
          

   Note Cygwin uses ``/'' as directory separator, and ``//X'' as a notation for Win32 drive X. Note also that you can't use ``c:/cygwin/bin'' because, for Cygwin, ``:'' is path separator character, as in UNIX.
   
   

3. Add an ACE_ROOT environment variable pointing to the root of your ACE wrappers source tree:

          % export ACE_ROOT=c:/work/cygwin/ACE_wrappers
          

   Note here you can't use the ``//X'' Cygwin notation as this is seen by Cygwin's compiler and it doesn't support that (it does support ``/'' as directory separator however).

   From now on, we will refer to the root directory of the ACE source tree as $ACE_ROOT.
   
   

4. Create a file called config.h in the $ACE_ROOT/ace directory that contains:

          #include "ace/config-cygwin32.h"
          

5. Create a file called platform_macros.GNU in the $ACE_ROOT/include/makeinclude directory containing:

          include $(ACE_ROOT)/include/makeinclude/platform_cygwin32.GNU
          

   In the above text, don't replace $(ACE_ROOT) with the actual directory, GNU make will take the value from the environment variable you defined previously.
6. On the Cygwin shell, change to the $ACE_ROOT/ace directory and run make:

          % cd $ACE_ROOT/ace
          % make
          

   This should create libACE.dll (the Win32 shared library) and libACE.dll (the Win32 import library for the DLL). Note the name for the ACE DLL on Cygwin follows the UNIX convention.
   
   

   If you want static libs also, you may run:

          % make static_libs=1
          

7. The same rules for Win32 search of DLLs apply for Cygwin. If you want to run some ACE programs from the Cygwin shell, you may need to add the directory for libACE.dll to your PATH:

          # export PATH=//c/work/cygwin/ACE_wrappers/ace:$PATH
          

   If you are using MPC generated Makefiles, then the DLLs have been placed in the lib directory instead of ace and thus your PATH addition would need to look like this:

          # export PATH=//c/work/mingw/ACE_wrappers/lib:$PATH
          

If you are using ACE as a DLL, you will need to modify your PATH variable as explained above.

You may want to check $ACE_ROOT/tests/README for the status of the various tests on Cygwin and the different Windows flavors.

Building and Installing ACE on VxWorks

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.

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 */

#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" [, ...]

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.

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

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

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.

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

Building ACE on Tornado/NT hosts for VxWorks targets.

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.

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

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
         

6. When using cygnus windows GNUTools on WinNT you have to start make with "--unix" option, otherwise WinNT shell cmd.exe is responded and not sh.exe, i.e.,

    make --unix static_libs=1
    

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

  Jaffar Shaikh's Notes for Building ACE and TAO for VxWorks on NT host

Scenario: I was building the ACE and TAO for VxWorks on NT. The target system was a PPC860 based chassis and another a NT host based card.

NT 4.0 workstation with 128 M RAM, 266MHz Pentium.

1) PERL: Active State's ActivePerl 5.6.0.618 for NT available as freeware from http://www.ActiveState.com/download/contrib/Microsoft/NT/InstMsi.exe

2) Tornado II .Release V 9904 from Windriver.

3) Cygwin GNU to build TAO. It is available for NT as a freeware from

http://www.cygwin.com/

The Cygwin Make (version 3.75) can only build the TAO not the Tornado II make (version 3.74)

On NT the environment Variables are set as follows, (from Control Panel-> System -> Environment)

I added following Environment variable entries to PATH

C:\Perl\bin\;

C:\tornado\host\x86-win32\bin;

C:\tornado\host\x86-win32\powerpc-wrs-vxworks\bin;

C:\tornado\host\x86-win32\lib\gcc-lib\powerpc-wrs-vxworks\cygnus-2.7.2-960126;

C:\Corba\Ace_wrappers\bin;

C:\Cygwin\bin;

C:\Cygwin\usr\bin;

C:\bin

Additional Environmental variables and the values,

CPU=PPC860

LD_LIBRARY_PATH=

SHELL=/bin/sh.exe

ACE_ROOT=/Corba/ACE_wrappers

WIND_BASE=/tornado

SHELL=/bin/sh.exe

TERM=pcbios

TAO_ROOT=/Corba/ACE_wrapper/Tao

CPP_LOCATION=/Program Files/Microsoft Visual Studio/VC98/Bin/CL.exe

GCC_EXEC_PREFIX=/tornado/host/x86-win32/lib/gcc-lib/

WIND_HOST_TYPE=x86-win32

PERL_PATH=/perl/bin/perl.exe

C:\Corba <-- Ace_wrappers (uzipped)

C:\tornado <-- Tornado installed

C:\Perl <-- Perl installed

C:\Cygwin <-- Cygwin installed

C:\bin <-- Copy these files,

Ace.dll, <-- After you build Ace

gperf.exe <-- After you build gperf

Cygwin1.dll, <-- After you install Cygwin

perl.exe, <-- After you install Perl

rm.exe <-- After you install Cygwin

sh.exe <-- After you install Cygwin

true <-- After you install Cygwin

1) C:\Corba\ACE_Wrappers\ace\config.h

with entry

#if defined (_MSC_VER) || (__BORLANDC__)

#include "ace/config-win32.h"

#undef ACE_HAS_EXCEPTIONS

#else

#include "ace/config-vxworks5.x.h"

#define ACE_HAS_IP_MULTICAST

#endif

2) C:\Corba\ACE_wrappers\include\makeinclude\platform_macros.GNU

WIND_BASE = /tornado

WIND_HOST_TYPE = x86-win32

include $(ACE_ROOT)/include/makeinclude/platform_vxworks5.x_g++.GNU

ACE_COMPONENTS=FOR_TAO (you may choose this option to build ACE library that supports TAO)

1) Build Ace.dll under NT

In MS Visual C++ open C:\Corba\ACE_wrappers\ace.dsw And build Ace DLL

Copy Ace.dll in C:\bin

2) Build gperf utility under NT

In MS Visual C++ open C:\Corba\ACE_wrappers\apps\gperf\src\gperf.dsw. Build gperf.exe

Copy gperf.exe to C:\bin

3) Mount Directries in Cygwin

Click on Cygnus Solutions -> Cygwin Bash Shell

Mount following directories by using mount command.

create respective directories first then use mount command

e.g. Create /Corba directory then use $mount -s "C:\Corba" /Corba

C:\Corba mount to /Corba

C:\tornado mount to /tornado

C:\Perl mount to /perl

C:\Cygwin mount to /cygwin

C:\bin mount to /bin

C:\Program Files mount to /Program Files

4) Build ACE in Cygwin

$cd /Corba/ACE_wrappers/ace

$make static_libs=1

This will build your ace library libACE.a for VxWorks. If you use option shared_libs=1 then the build will be libACE.so. The other options are same as follows.

5) Build TAO in Cygwin

$cd $TAO_ROOT/tao

$make debug=0 optimize=1 static_libs_only=1 minimum_orb=1

for shared libs use shared_libs=1

The minimum Tao does not have following components,

Dynamic Skeleton Interface

Dynamic Invocation Interface

Dynamic Any

Interceptors

Interface Repository

Advanced POA features

CORBA/COM interworking

You may play around with above options to find suitable build for your needs. For example when you give option debug=1 all the debug symbols will be created and the build will huge in size. The debug symbols are necessary when you want to debug your code.

Building and Installing ACE Network Services

Building and Installing ACE Network Services on UNIX

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:$ACE_ROOT/lib:$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 on RTEMS

export RTEMS_MAKEFILE_PATH=/opt/rtems/CPU-rtems/BSP
# setup the build structure
cd ACE_wrappers

# create the host (e.g. Linux in this case) build tree
./bin/create_ace_build Linux_g++
cd build/Linux_g++/ace
ln -s ../../../ace/config-linux.h config.h
cd ../include/makeinclude
ln -s ../../../../include/makeinclude/platform_linux.GNU platform_macros.GNU
cd ../../../..

# create the target build tree
./bin/create_ace_build rtems
cd build/rtems/TAO
/bin/rm -r TAO_IDL
ln -s ../../Linux_g++/TAO/TAO_IDL .
cd ../ace
ln -s ../../../ace/config-rtems.h config.h
cd ../include/makeinclude
ln -s ../../../../include/makeinclude/platform_rtems.x_g++.GNU platform_macros.GNU
cd ../../../..

# build the host side of things
cd build/Linux_g++
export ACE_ROOT=`pwd`; export LD_LIBRARY_PATH=`pwd`/ace:`pwd`/lib:$LD_LIBRARY_PATH
cd ace
make

# optionally build the ACE tests
cd ../tests
make

cd ../TAO
make

# build the target side of things
cd ../rtems
export ACE_ROOT=`pwd`
cd ace
make
cd ../tests
# build rtems_init.o by hand
make -f  ../include/makeinclude/Makefile.rtems rtems_init.o
make
cd ../TAO
make

Building and Installing ACE Network Services on Win32

Building and Installing The ACE_SSL Library

The first step for all platforms is to build and install the OpenSSL distribution. Then the ACE_SSL library must be built according to the instructions below.

Unix

1. Make sure the OpenSSL header file directory is in your compiler's include path, and that OpenSSL libraries are in your library link/load path (e.g. LD_LIBRARY_PATH). If you installed OpenSSL into a set of directories unknown by the compiler, then set the following variables in your platform_macros.GNU file:

   PLATFORM_SSL_CPPFLAGS	Platform preprocessor options for OpenSSL (e.g. -I...)
   PLATFORM_SSL_LDFLAGS	Platform linker options for OpenSSL (e.g. -L...)
   PLATFORM_SSL_LIBS	Platform libraries required with OpenSSL (e.g. -lssl -lcrypto)

   
   

2. Build ACE as described above. When building ACE, add "ssl=1" to your make command line invocation, or add it to your platform_macros.GNU file.
3. Build the ACE_SSL library in the $ACE_ROOT/ace/SSL directory. The ACE_ROOT environment variable should be set prior to this point.

Microsoft Visual Studio

1. Set the OpenSSL include/header directory path under the Directories tab - Include Files setting in the Tools->Options dialog. A typical value would be something like: openssl-0.9.6\inc32
2. Set the OpenSSL library directory path under the Directories tab - Library Files setting in the Tools->Options dialog. A typical value would be something like: openssl-0.9.6\out32dll
3. Open the ACE.dsw workspace, and refer to the ACE build and installation instructions above for details on creating a config.h configuration header for this platform. Once the config.h file has been created, build the ACE_SSL project.

Borland C++

Support for building TAO's SSLIOP pluggable protocol with Borland C++ does exist. First get a patch for the Open SSL makefile from http://www.tenermerx.com/tao_bcb/index.html. Then build the OpenSSL library. When you use the DLL version of ACE+TAO you have to build a DLL version of OpenSSL. Then you must set the environment variable SSL_ROOT to the location of your OpenSSL and then build ACE and TAO as normally.

What Do I Need to Build for TAO?

I usually make:

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

    TAO_ORBSVCS = Naming Time Trader ImplRepo

System Resource Requirements

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 I untar the distribution. They are meaningless in my environment (Files named '*.dsw' and '*.dsp' are used for MSVC++ and files named '*.bor' are for Borland C++ Builder.)

  Finally, to save space, may want to run 'make clean' after 'make'. It removes generated object files and leaves libraries/executables intact. If you want to remove any of the libraries/executables, as well, try 'make realclean'.

Advanced Topics

• Porting ACE and TAO to a New OS Platform
• Using GNU's Autoconf with ACE
  • This support is currently a work-in-progress, and is hence disabled. It will be completed and re-enabled as soon as someone funds the work to do so.
• Non-static ACE_Object_Manager
• Cloning the Source Tree
• Building CORBA Versions of ACE
• Additional Build Tips for MVS
• Makefile Flags
• Version Control
• ACE Makefile hints
• ACE SSL effort

Non-static ACE_Object_Manager

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 *[])

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

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

Then create a ./build subdirectory someplace, e.g., under $ACE_ROOT. Once this is done, then invoke the top-level Makefile with the "clone" target, e.g.:

% cd $ACE_ROOT
% mkdir build-SunOS5
% cd build-SunOS5
% make -f ../Makefile clone
% setenv ACE_ROOT $cwd
% make

This will establish a complete tree of links. In addition, make sure you set your LD_LIBRARY_PATH to $ACE_ROOT/ace:$ACE_ROOT/lib:$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.

Additional Build Tips for MVS

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

% make -j n

which allows parallel compilation. The number n should typically be the number of CPUs. It is likely that builds will be faster even on single-CPU UNIX machines with make -j 2.

ACE further 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).
include_env      Support old-style ACE_TRY_ENV declarations in methods.
                 This switch is necessary for compiling TAO applications
                 in the native exception configuration that were written
                 for TAO versions before 1.2.2.
                 In TAO 1.2.2, new macros were introduced that supercede
                 the direct ACE_TRY_ENV declarations. These are the
                 ACE_ENV_ARG macros that are defined in ace/CORBA_macros.h
                 and are documented in docs/exceptions.html.
                 This switch only affects the exceptions=1 configuration.
                 It is for backward compatibility only.
                 There will be warnings about unused _ACE_environment_variable
                 parameters when using include_env=1.
                 If possible, do not use it, but instead change your TAO
                 applications to use the ACE_ENV_ARG macros.
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.
pace             Enable PACE as the underpinnings of ACE_OS.
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.
fl_reactor       Build the FlReactor.
tk_reactor       Build the TkReactor.
qt_reactor       Build the QtReactor.
gtk_reactor      Build the GtkReactor.
ssl              Build with OpenSSL support.
rapi             Build with RAPI
split            Build the library by first splitting up the ACE source
                   to several files, with one object code entity for each
                   source file. This allows an application that is linked
                   with ACE to extract _exactly_ what it needs from the
                   library, resulting in a smaller executable.  Setting this
                   to 1 overrides debug to 0.

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.