ChangeLogTag:Tue Feb 13 09:09:01 2001 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 130 insertions, 30 deletions

diff --git a/TAO/TAO-INSTALL.html b/TAO/TAO-INSTALL.html
index 6f1d68799bd..df108775dc1 100644
--- a/TAO/TAO-INSTALL.html
+++ b/TAO/TAO-INSTALL.html
@@ -132,16 +132,101 @@ If you are building TAO for a VxWorks target, please see the detailed
 instructions for building and installing ACE and TAO in <a
 href="../ACE-INSTALL.html#vxworks">$ACE_ROOT/ACE-INSTALL.html</a>.<p>
 
-Cross-compiling TAO is not much different than building it for
-self-host.  The one major difference is that TAO's IDL compiler must
-be built and run on the host; it's not necessary to run it on the
-target.  It's easiest to set this up by using a symlink (Unix) or copy
-of <code>tao_idl</code> (NT).  By way of example, here is how I setup
-my Unix (SunOS5, using g++) workspace to support cross-compilation
-(for VxWorks).  It assumes that the ACE+TAO distribution has been
-unpacked, with TAO below ACE_wrappers.  It uses the
-ACE_wrappers/bin/create_ace_build script to create a shadow build
-tree:<p>
+    <P>Cross-compiling TAO is not much different than building it for
+      self-host.  The one major difference is that TAO's IDL compiler
+      must be built and run on the host; it's not necessary to run it
+      on the target.
+      There are several ways to do this, below we document the two
+      most common approaches:
+      </P>
+
+    <H4>Modifying the default location for the IDL compiler</H4>
+
+    <P>By default TAO assumes that the IDL compiler is located in:
+      <CODE>$TAO_ROOT/TAO_IDL/tao_idl</CODE> and that the GPERF tool
+      is located in <CODE>$ACE_ROOT/bin/gperf</CODE>, this is fine for
+      hosted builds, but not for cross-compilation.
+      Unfortunately there is no good default for cross-compilation
+      builds because different sites choose a different location for
+      their tools.
+    </P>
+    <P>You can override the default values by adding two lines in your
+      platform_macros.GNU file, as follows:
+<PRE>
+$ echo 'TAO_IDL := /your/path/tao_idl' \
+     >> platform_macros.GNU
+$ echo 'TAO_IDLFLAGS := -g /your/path/gperf' \
+</PRE>
+    </P>
+    <P>You could even use:
+<PRE>
+$ echo 'TAO_IDL := tao_idl' \
+     >> platform_macros.GNU
+$ echo 'TAO_IDLFLAGS := -g gperf' \
+</PRE>
+    if the tools are in your path.
+    </P>
+    
+    <P>Obviously you must first build the tools for the host platform,
+      typically you would do this as follows:
+<PRE>
+# (1) Create a clone directory for the host:
+
+$ cd ACE_wrappers
+$ mkdir -p build/HOST
+$ ./bin/create_ace_build build/HOST
+
+# (2) Configure the host build:
+
+$ echo '#include "ace/config-HOST.h"' > build/HOST/ace/config.h
+$ echo 'include $(ACE_ROOT)/include/makeinclude/platform_HOST.GNU' \
+     > build/HOST/include/makeinclude/platform_macros.GNU
+
+# Often host builds are static:
+$ echo 'static_libs_only=1' \
+     >> build/HOST/include/makeinclude/platform_macros.GNU
+
+# (3) Build the host tools
+
+$ cd build/HOST
+$ export ACE_ROOT=$PWD
+$ make -C ace
+$ make -C apps/gperf
+$ make -C TAO/TAO_IDL
+</PRE>
+
+    <P>Then configuring the location of the tools for the target
+      could be done as shown here:
+<PRE>
+# (4) Create a clone directory for the target:
+
+$ cd ACE_wrappers
+$ mkdir -p build/TARGET
+$ ./bin/create_ace_build build/TARGET
+
+# (5) Configure the target build:
+
+$ echo '#include "ace/config-TARGET.h"' > build/HOST/ace/config.h
+$ echo 'include $(ACE_ROOT)/include/makeinclude/platform_TARGET.GNU' \
+     > build/TARGET/include/makeinclude/platform_macros.GNU
+
+# (6) Configure the TARGET build to use the HOST IDL compiler and
+#     gperf tools, as described above.
+</PRE>
+
+    <H4>Alternative configuration, using links</H4>
+
+    <P>Some developers prefer to set up the host tools using symbolic
+      links (Unix) or copy of <code>tao_idl</code> (NT).
+      By way of example, here is how you could setup a
+      croos-compilation environment for Unix,
+      the host is <CODE>SunOS5/g++</CODE>,
+      the target is <CODE>VxWorks</CODE>.
+      It assumes that the ACE+TAO distribution has been
+      unpacked, with TAO below ACE_wrappers.  It uses the
+      ACE_wrappers/bin/create_ace_build script to create a shadow
+      build 
+      tree:
 <ol>
   <li><code>cd ACE_wrappers</code>
   <li><code>bin/create_ace_build SunOS5_g++</code>
@@ -149,9 +234,10 @@ tree:<p>
   <li><code>cd build/vxworks/TAO</code>
   <li><code>/bin/rm -r TAO_IDL</code>
   <li><code>ln -s ../../SunOS5_g++/TAO/TAO_IDL</code>
-</ol><p>
+</ol>
+  </P>
 
-To build on the host:
+      <P>To build on the host:
 <ol>
   <li><code>cd build/SunOS5_g++</code>
   <li><code>export ACE_ROOT=`pwd`;
@@ -162,24 +248,38 @@ To build on the host:
   <li><code>export ACE_ROOT=`pwd`</code>
   <li><code>(cd ace; make && cd ../tests; make && cd ../TAO; make) &gt;
     make.log</code>
-</ol><p>
-
-For NT hosts, please see the detailed instructions for building and
-installing ACE and TAO in <a
-href="../ACE-INSTALL.html#vxworks">../ACE-INSTALL.html</a>.  For
-NT hosts, see <a href="../ACE-INSTALL.html#VxWorks/NT">Building
-ACE on Tornado/NT hosts for VxWorks targets</a><p>
-
-Please note that dynamic loading of libraries is not supported by TAO
-for any cross-compiled target.  Therefore, dynamic service
-configuration of the TAO ORB is not supported.<p>
-
-If using perfect hashing, TAO_IDL needs gperf to be built on the host.
-That's the default on many platforms.  First, build <code>gperf</code>
-in the <code>ACE_wrappers/apps/gperf/src/</code> directory.  Then, add
-a symlink or copy to the <code>bin/</code> directory for the
-target.<p>
-
+</ol></p>
+
+    <P>For NT hosts, please see the detailed instructions for building
+      and installing ACE and TAO in
+      <a href="../ACE-INSTALL.html#vxworks">../ACE-INSTALL.html</a>,
+      and
+      <a href="../ACE-INSTALL.html#VxWorks/NT">Building ACE on
+	Tornado/NT hosts for VxWorks targets</a>
+    </P> 
+
+    <P>Please note that dynamic loading of libraries is not supported
+      by TAO for any cross-compiled target.  Therefore, dynamic
+      service configuration of the TAO ORB is not supported.
+    </p>
+
+    <P>If using perfect hashing, TAO_IDL needs gperf to be built on
+      the host. That's the default on many platforms.  First, build
+      <code>gperf</code> in the
+      <code>ACE_wrappers/apps/gperf/src/</code> directory.  Then, add
+      a symlink or copy to the <code>bin/</code> directory for the
+      target.
+    </P>
+
+    <H4>Which one is right for me?</H4>
+    
+    <P>Using links to cross-compile TAO may appear simpler at first
+      glance.  However, storing the location in the
+      <CODE>platform_macros.GNU</CODE> is more amenable for
+      sites where many developers share the same configuration files,
+      or where ACE+TAO are compiled once and used by a medium or large
+      size group.
+    </P>
 
 <HR><P>
 <H3>On Windows NT</H3>