ACE/docs/ACE-porting.html

   1 <!--  -->
   2
   3 <HTML>
   4 <HEAD>
   5    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   6    <META NAME="Generator" CONTENT="Microsoft Word 97">
   7    <META NAME="Template" CONTENT="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html
   8 .dot">
   9    <META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (Win95; I) [Netscape]">
  10    <TITLE>Porting ACE and TAO to a New OS Platform</TITLE>
  11 </HEAD>
  12 <BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#FF0000">
  13
  14 <HR><P> <H3>Porting ACE and TAO to a New OS Platform</H3><P>
  15
  16 <A HREF="https://www.dre.vanderbilt.edu/ACE">ACE</A> and  <A
  17 HREF="https://www.dre.vanderbilt.edu/TAO">TAO</A> have been
  18 ported to <A HREF="https://www.dre.vanderbilt.edu/versions.html">many
  19 OS platforms</A>.  Porting ACE and TAO to new platforms is
  20 fairly easy.  The following document describes the step-by-step
  21 process to use when porting the various <A
  22 HREF="https://www.dre.vanderbilt.edu/~schmidt/ACE-overview.html">components
  23 and layers</A> in ACE to a new OS platform.  Once ACE is ported, it is
  24 straightforward to port TAO as well.<P>
  25
  26 Before starting a port that you plan to contribute back to the
  27 ACE+TAO open-source community, we recommend that you do the
  28 following:
  29
  30 <UL>
  31 <LI> Read and follow the <A HREF="ACE-guidelines.html">programming style
  32     guidelines</A> we use when writing ACE and TAO code,
  33     which will make it much easier to integrate and maintain your port
  34     in the source tree. <P>
  35
  36 <LI> Contact <A HREF="mailto:d.schmidt@vanderbilt.edu">Douglas
  37     C. Schmidt</A> and let him know that you're planning to contribute
  38     a port, which will make it make easier to work out the logistics
  39     of when/how the port will be integrated. <P>
  40 </UL>
  41
  42 <hr align=left width="50%"><P>
  43 <H4>Create a <CODE>config.h</CODE> Header File for the Target OS Platform</H4>
  44
  45 A <CODE>config-*.h</CODE> header file exists in <A
  46 HREF="../ace/">$ACE_ROOT/ace</A> for each platform to which ACE has
  47 been ported.  This file contains the portability macros for each
  48 particular configuration of ACE.  A complete description of the
  49 existent macros can be found in the <A
  50 HREF="../ace/README">$ACE_ROOT/ace/README</A> file. <P>
  51
  52 Currently, you must edit this file by hand to port it to new OS
  53 platforms.  It's a good idea to use
  54 the <CODE>config-*.h</CODE> files for platforms with similar
  55 characteristics as examples.
  56
  57 <hr align=left width="50%"><P>
  58 <H4>Port the <CODE>ACE_OS</CODE> Namespace</H4>
  59
  60 The <CODE>ACE_OS</CODE> namespace encapsulates most of variation
  61 between the different OS implementations, <EM>e.g.</EM>, UNIX, Win32,
  62 and various real-time operating systems.  It is the core of the ACE OS
  63 abstraction layer.  Most work required to port ACE to a new OS
  64 platform resides in this namespace.  There are <EM>many</EM> examples
  65 of how ACE has been ported to other operating systems in the
  66 <CODE>ACE_OS</CODE> class in the
  67 <CODE>$ACE_ROOT/ace/OS_NS_*.{h,inl,cpp}</CODE> files. <P>
  68
  69 Optional features in pthreads are covered by <CODE>ACE_HAS_*</CODE>
  70 and/or <CODE>ACE_LACKS_*</CODE> macros, which are described in the <A
  71 HREF="../ace/README">$ACE_ROOT/ace/README</A> file.  Particular
  72 platform features, such as DCE pthreads calls that end in
  73 <CODE>_np</CODE>, should be bracketed by platform defines rather than
  74 by inventing more <CODE>ACE_HAS_*</CODE> or <CODE>ACE_LACKS_*</CODE>
  75 definitions. <P>
  76
  77 An important part of porting ACE to a new platform is to map the
  78 threading API correctly.  Currently, ACE has support for the following
  79 thread APIs: <P>
  80
  81 <UL>
  82 <LI> <B>POSIX Pthreads</B> (<CODE>ACE_HAS_PTHREADS</CODE>) -Final standard (also
  83     called draft 10) [MIT, Linux]. <P>
  84
  85 <LI> <B>Win32 Threads</B> (<CODE>ACE_HAS_WTHREADS</CODE>) - Windows
  86     NT, Windows '95/98<P>
  87
  88 <LI> <B>VxWorks Tasks</B> (<CODE>ACE_VXWORKS</CODE>) - VxWorks <P>
  89 </UL>
  90
  91 If your OS platform does not support any of these threading packages,
  92 you must port the <CODE>ACE_OS::thr_*</CODE> functions. <P>
  93
  94 <hr align=left width="50%"><P>
  95 <H4>Port the C++ Wrapper Facade Components</H4>
  96
  97 After porting the <CODE>ACE_OS</CODE> namespace, the next step is to
  98 port all of the ACE C++ wrapper facade components, such as sockets,
  99 threads, synchronization mechanisms.  A full list of the categories
 100 and classes can be found in the <A
 101 HREF="ACE-categories.html">$ACE_ROOT/ACE-categories</a> file.  It is
 102 easiest to concentrate on porting one category at the time.  The ACE
 103 release contain a <A HREF="../tests/README">regression test suite</A>
 104 in the <A HREF="../tests/">$ACE_ROOT/tests/</A> directory.  These
 105 tests can be used to validate the correctness of the various ACE C++
 106 wrapper facades as they are ported. <P>
 107
 108 <hr align=left width="50%"><P>
 109 <H4>Port the Higher-level Framework Components of ACE</H4>
 110
 111 Having ported (and tested) all the components of the ACE OS adaptation
 112 layer and C++ wrapper facades, you can proceed to port the higher
 113 level components of ACE, such as the Reactor, Service Configurator,
 114 Connector, Acceptor, and Streams frameworks.  At this point, it should
 115 be relatively easy to port the rest of ACE because most of the
 116 platform-dependent code is localized in the lower layers of ACE. <P>
 117
 118 <hr align=left width="50%"><P>
 119 <H4>Port TAO</H4>
 120
 121 After porting and successfully testing all the ACE framework
 122 components, it should be straightforward to port and <A
 123 HREF="../TAO/TAO-INSTALL.html">install</A> TAO because the bulk
 124 of their platform-dependent code is localized in ACE.  Typically, the
 125 only problems that arise when porting TAO is bugs and
 126 limitations with C++ compilers. <P>
 127
 128 <HR><P>
 129 <H3>C++ Features Required to Port ACE and TAO</H3>
 130
 131 ACE and TAO have been ported to most C++ compilers.  The
 132 following is a list of which C++ features a compiler must support in
 133 order to compile ACE and TAO:
 134
 135 <UL>
 136 <LI> <B>Templates</B> -- The C++ compiler must support templates.
 137     However, it need not support template member functions and of
 138     the advanced concepts outlined in <A
 139     HREF="http://www.moderncppdesign.com/"> Modern C++ Design</A>. <P>
 140
 141 <LI> <B>Multiple inheritance and dynamic binding</B> -- The C++
 142     compiler must support multiple inheritance and dynamic
 143     binding. <P>
 144
 145 <LI> <B>Namespaces</B> -- ACE+TAO utilizes C++ namespaces, so the
 146     C++ compiler must support them.<P>
 147
 148 <LI> <B>ANSI casts and RTTI</B> -- ACE+TAO uses the ANSI C++
 149     casts, so the C++ compiler  must support them, which implies
 150     support for RTTI.<P>
 151
 152 </UL>
 153
 154 The following is a list of which C++ features that ACE and TAO can
 155 take advantage of if a compiler supports them:
 156
 157 <UL>
 158 <LI> <B>Exceptions</B> -- The ACE library itself is ``exception
 159     neutral,'' <EM>i.e.,</EM> it does not catch or throw C++
 160     exceptions.  However, you can use exceptions in code
 161     that uses ACE including throwing exceptions inside call back
 162     methods, as long as you provide the code to handle it.
 163     TAO requires the use of C++ exceptions,
 164     <CODE>ACE_HAS_EXCEPTIONS</CODE> must be defined. <P>
 165
 166 <LI> <B>STL</B> -- Unfortunately many of the platforms that ACE
 167         supports don't have an STL library.  Moreover, different versions
 168         of STL behave differently.  ACE therefore does not depends on
 169         STL and does not use it internally.  If your target
 170         platform(s) support STL you should be able to
 171         use it with ACE and TAO without problems, though your C++
 172         compiler may have problems with it (this is beyond the scope
 173         of ACE, however). <P>
 174
 175         If you are considering STL, you might consider
 176         <A HREF="http://www.stlport.org/">STLport</a>,
 177         which is a port of the SGI STL to numerous platforms that ACE and
 178         TAO also support. <P>
 179
 180 </UL>
 181
 182 <P><HR><P>
 183
 184 Back to the <A
 185 HREF="http://www.dre.vanderbilt.edu/~schmidt/ACE-documentation.html">ACE
 186 documentation</A> page.<BR>
 187 Back to <A HREF="index.html">ACE Documentation Home</A>.
 188
 189 <!--#include virtual="/~schmidt/cgi-sig.html" -->
 190 </BODY>
 191 </HTML>