ChangeLogTag:Mon Oct 24 10:21:39 2005 Ossama Othman <ossama@dre.vanderbilt.edu>

1 files changed, 124 insertions, 1 deletions

diff --git a/docs/ACE-guidelines.html b/docs/ACE-guidelines.html
index ec975667c53..f3b661fe882 100644
--- a/docs/ACE-guidelines.html
+++ b/docs/ACE-guidelines.html
@@ -236,6 +236,8 @@ not defined.  The correct way to write that guard is:
 #if defined (__FreeBSD__)  &&  __FreeBSD__ < 3
 </pre>
 
+If using g++, problems like this can be flagged as a warning by using the "<code>-Wundef</code>" command line option.
+
     <li>Try to centralize <code>#ifdef</code>s with <code>typedef</code>s
         and <code>#define</code>s.  For example, use this:
         <pre>
@@ -912,6 +914,127 @@ Foo::bar ()
   </ul><p>
 </ul>
 
+<hr>
+<h3><a href="http://www.cs.wustl.edu/~schmidt/ACE-overview.html">ACE</a>
+  Shared Libary Guidelines</h3>
+    <ul>
+      <li>
+	<p>
+	  Create a separate export macro for each dynamic library.  A
+	  header file containing the export macro and additional
+	  support macros should be generated by using the <a
+	    href="../bin/generate_export_file.pl">ACE_wrappers/bin/generate_export_file.pl</a> Perl script.
+	  </p>
+      </li>
+      <li>
+	<p>
+	  Make sure that your classes, structures and free functions
+	  are annotated with this export macro.  The only exceptions
+	  are pure template classes, structures and free functions.
+	</p>
+        <p>
+	  Only classes (and structures, free functions, etc) that are
+	  part of the library public interface must be exported
+	  (e.g. declared with an export macro).  Those that are only
+	  meant to be used internally need not be exported,
+	  particularly for g++ <code>&gt;=</code>4.0  since doing so
+	  defeats some neat optimizations.  Here's a common case in
+	  where an export macro is generally used unnecessarily:
+	</p>
+	<blockquote>
+	  <pre>
+class FooExport Foo
+{
+public:
+  virtual void kung_fu () = 0;
+};
+
+class FooExport Bar : public Foo
+{
+public:
+  virtual void kung_fu ()  { ... }
+};
+
+class FooExport FooFactory
+{
+public:
+  Foo * make_foo ()
+    {
+      // Assume that this implementation is hidden from
+      // the application and is consequently out of line.
+      return new Bar();
+    }
+};
+	  </pre>
+	</blockquote>
+	<p>
+	  Here the application is only meant to invoke operations
+	  through a pointer or reference to the abstract base class
+	  "<code>Foo</code>" created by the "<code>FooFactory</code>",
+	  not the "<code>Bar</code>" subclass.  In this case,
+	  exporting "<code>Bar</code>" is unnecessary.  If your
+	  concrete class is meant to be used outside of the shared
+	  library (e.g. as a template parameter, within a
+	  <code>dynamic_cast&lt;&gt;</code>, etc) you must then export
+	  it.  Otherwise, avoid doing so if you can.
+	</p>
+      </li>
+      <li>
+	<p>
+	  Make sure that you specify that you are creating a dynamic
+	  library in your <a href="../MPC/README">MPC</a> file by adding
+	  a <code>sharedname</code> tag.
+	</p>
+      </li>
+      <li>
+	<p>
+	  Make sure that you add the <code>FOO_BUILD_DLL</code>
+	  preprocessor symbol to the <code>dynamicflags</code> of the
+	  MPC project that is used to build a library.  Note that the
+	  export files are setup such that when this macro is defined,
+	  the symbols are exported, otherwise they are imported.  The
+	  default behaviour is to set up for import so that clients of
+	  your library don't need to worry about arcane build flags
+	  like <code>FOO_BUILD_DLL</code> in their build setup.  This
+	  ties back to the first item.
+	</p>
+      </li>
+      <li>
+	<p>
+	  When you specify the order of libraries to link to, make
+	  sure that the dependent libraries come after the libraries
+	  which depend on them, i.e., your link line should always
+	  contain <code>-lDependsOnFoo -lFoo</code>.  Note that this
+	  is not a requirement on GNU/Linux but linkers on other
+	  platforms are not as forgiving.
+	</p>
+      </li>
+      <li>
+	<p>
+	  Use the <code>ACE_SINGLETON_DECLARE</code> macro to declare
+	  a class as a singleton.  Declare exported (i.e. default
+	  visibility)  singleton templates prior to typedefs that
+	  reference them.  This prevents g++ 4.0 from silently making
+	  their visibility hidden (see <a
+	    href="http://deuce.doc.wustl.edu/bugzilla/show_bug.cgi?id=2260">Bug 2260</a> for details).
+	</p>
+      </li>
+      <li>
+	<p>
+	  Avoid inlining virtual functions in classes that must be
+	  exported since doing so can cause RTTI related problems
+	  (e.g. <code>dynamic_cast&lt;&gt; failures</code>) when using
+	  g++ &gt;= 4.0 due to our use of that compiler's "visibility
+	  attribute" support that is tied in to the export macros.
+	  This includes virtual destructors automatically created by
+	  the compiler when you don't declare one.  Make sure you
+	  define a no-op out-of-line virtual destructor if your base
+	  class has a virtual destructor since you may otherwise run
+	  into the mentioned RTTI problems.
+	</p>
+      </li>
+    </ul>
+
 
 <hr>
 <h3><a href="http://www.cs.wustl.edu/~schmidt/ACE-overview.html">ACE</a>
@@ -1169,7 +1292,7 @@ eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}'
 <hr><p>
   <font size=-1>
 <!-- hhmts start -->
-Last modified: Tue Sep 20 14:06:27 CDT 2005
+Last modified: Mon Oct 24 10:18:07 Pacific Daylight Time 2005
 <!-- hhmts end -->
   </font><p>