<dd><p class="Body"><a name="84481"> </a>Modules written in C++ must undergo an additional host processing step before being downloaded to a VxWorks target. This extra step (called <i class="term">munching</i>, by convention) initializes support for static objects and ensures that when the module is downloaded to VxWorks, the C++ run-time support is able to call the correct constructors and destructors in the correct order for all static objects.</p><dd><p class="Body"><a name="84511"> </a>The following commands will compile <b class="file">hello.cpp</b>, then munch<b class="file"> hello.o</b>, resulting in the munched file <b class="file">hello.out</b> suitable for loading by the Tornado module loader:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85814">cc68k -I<i class="textVariable">installDir</i>/target/h -DCPU=MC68020 -nostdinc -fno-builtin \         -c hello.cpp nm68k hello.o | wtxtcl <i class="textVariable">installDir</i>/host/src/hutils/munch.tcl \         -asm 68k &gt; ctdt.c cc68k -c ctdt.c ld68k -r -o hello.out hello.o ctdt.o</a></b></pre></dl></dl></dl><dl class="margin"><dd><p class="table" callout><table border="0" cellpadding="0" cellspacing="0"><tr valign="top"><td valign="top" width="40"><br><img border="0" alt="*" src="icons/note.gif"></td><td><hr><div class="CalloutCell"><a name="85846"><b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">NOTE:  </font></b></a>You can substitute the actual name of your <i class="textVariable">installDir</i> or use <b class="symbol_UC">$WIND_BASE</b> (UNIX) or <b class="symbol_UC">%WIND_BASE%</b> (Windows).</div></td></tr><tr valign="top"><td></td><td><hr></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p callout><dd><p class="table" callout><table border="0" cellpadding="0" cellspacing="0"><tr valign="top"><td valign="top" width="40"><br><img border="0" alt="*" src="icons/caution.gif"></td><td><hr><div class="CalloutCell"><a name="85116"><b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">CAUTION:  </font></b></a>The <i class="title">GNU ToolKit User's Guide: Using ld </i>describes a <b class="command">-Ur</b> option for resolving references to C++ constructors. That option is for native development, not for cross-development. Do not use <b class="command">-Ur</b> with C++ modules for VxWorks.</div></td></tr><tr valign="top"><td></td><td><hr></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p callout></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84526">5.2.6  &nbsp;&nbsp;Static Constructors and Destructors</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="85852"> </a>After munching, downloading, and linking, the static constructors and destructors must be called.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="85851">Calling Static Constructors and Destructors Interactively</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84528"> </a>VxWorks provides two strategies for calling static constructors and destructors interactively:</p></dl><dl class="margin"><dd><div class="Item"><a name="84529"> </a><i class="term">automatic</i> </div><dl class="margin"><dd><div class="Indent"><a name="84530"> </a>Static <i class="emphasis">constructors</i> are called as a side effect of downloading. Static <i class="emphasis">destructors</i> are called as a side effect of unloading.</div><br></dl><dd><div class="Item"><a name="84531"> </a><i class="term">manual</i> </div><dl class="margin"><dd><div class="Indent"><a name="84532"> </a>Static constructors and destructors are called indirectly by invoking <b class="routine"><i class="routine">cplusCtors</i></b><b>(&nbsp;)</b> and <b class="routine"><i class="routine">cplusDtors</i></b><b>(&nbsp;)</b>.</div><br></dl></dl><dl class="margin"><dd><p class="Body"><a name="84534"> </a>Use <b class="routine"><i class="routine">cplusXtorSet</i></b><b>(&nbsp;)</b> to change the strategy; see its entry in the <b class="command">windsh</b> reference entry for details. To report on the current strategy, call <b class="routine"><i class="routine">cplusStratShow</i></b><b>(&nbsp;)</b>.</p><dd><p class="Body"><a name="85549"> </a>Under the automatic strategy, which is the default, static constructors are called immediately after a successful download. If the automatic strategy is set <i class="emphasis">before</i> a module is downloaded, that module's static constructors are called before the module loader returns to its caller. Under the automatic strategy, the module unloader calls a module's static destructors before actually unloading the module.</p><dd><p class="Body"><a name="84536"> </a>The manual strategy causes static constructors to be called as a result of invoking <b class="routine"><i class="routine">cplusCtors</i></b><b>(&nbsp;)</b>. Refer to the entries for <b class="routine"><i class="routine">cplusCtors</i></b><b>(&nbsp;)</b> and <b class="routine"><i class="routine">cplusDtors</i></b><b>(&nbsp;)</b> in the <b class="command">windsh</b> reference for more information. To invoke all currently-loaded static constructors or destructors, manual mode can be used with no argument. Manual mode can also be used to call static constructors and destructors explicitly on a module-by-module basis.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="84540">Constructors and Destructors in System Startup and Shutdown</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84541"> </a>When you create bootable VxWorks applications, call static constructors during system initialization. Modify the <b class="routine"><i class="routine">usrRoot</i></b><b>(&nbsp;)</b> routine in <b class="file">usrConfig.c</b> to include a call to <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b>. This calls all static constructors linked with your system.</p><dd><p class="Body"><a name="84544"> </a>To modify <b class="file">usrConfig.c</b> to call <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b>, locate the C++ initialization sections:</p><dl class="margin"><dd><pre class="Code2"><b><a name="84545">#ifdef INCLUDE_CPLUS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* C++ product */     cplusLibInit (); #endif  #ifdef INCLUDE_CPLUS_MIN&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* C++ product */     cplusLibMinInit (); #endif</a></b></pre></dl><dd><p class="Body"><a name="84546"> </a>Next, add <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b> to one or both sections, depending on your system requirements. In the following example, <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b> is called only when minimal C++ is configured:</p><dl class="margin"><dd><pre class="Code2"><b><a name="85125">#ifdef INCLUDE_CPLUS_MIN&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* C++ product */     cplusLibMinInit ();     cplusCtorsLink (); #endif</a></b></pre></dl></dl></dl><dl class="margin"><dd><p class="table" callout><table border="0" cellpadding="0" cellspacing="0"><tr valign="top"><td valign="top" width="40"><br><img border="0" alt="*" src="icons/caution.gif"></td><td><hr><div class="CalloutCell"><a name="85130"><b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">CAUTION:  </font></b></a>Static objects are not initialized until the call to <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b>. Thus, if your application uses static objects in <b class="routine"><i class="routine">usrRoot</i></b><b>(&nbsp;)</b>, call <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b> before using them. <br> <br>For <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b> to work correctly, you must perform the munch operation on the fully-linked VxWorks image rather than on individual modules.</div></td></tr><tr valign="top"><td></td><td><hr></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p callout><dl class="margin"><dd><p class="Body"><a name="85137"> </a>A corresponding routine, <b class="routine"><i class="routine">cplusDtorsLink</i></b><b>(&nbsp;)</b>, is provided to call all static destructors. This routine is useful in systems that have orderly shutdown procedures. Include a call to <b class="routine"><i class="routine">cplusDtorsLink</i></b><b>(&nbsp;)</b> at the point in your code where it is appropriate to call all static destructors that were initially linked with your system.</p><dd><p class="Body"><a name="84560"> </a>The <b class="routine"><i class="routine">cplusCtorsLink</i></b><b>(&nbsp;)</b> and <b class="routine"><i class="routine">cplusDtorsLink</i></b><b>(&nbsp;)</b> routines do not call static constructors and destructors for modules that are downloaded after system initialization. If your system uses the module downloader, follow the procedures described in <a href="c-wfc2.html#85851"><i class="title">Calling Static Constructors and Destructors Interactively</i></a>.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="84565">5.2.7  &nbsp;&nbsp;Template Instantiation</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="84567"> </a>Our C++ toolchain supports three distinct template instantiation strategies. The simplest (and the one that is used by default in VxWorks makefiles) is <i class="term">implicit instantiation</i>. In this case code for each template gets emitted in every module that needs it. For this to work the body of a template must be available in each module that uses it. Typically this is done by including template function bodies along with their declarations in a header file. The disadvantage of implicit instantiation is that it may lead to code duplication and larger application size. </p><dd><p class="Body"><a name="84568"> </a>The second approach is to explicitly instantiate any templates you require using the syntax found in <a href="c-wfc2.html#84593">Example&nbsp;5-1</a>. In this case you should compile with <b class="command">-fno-implicit-templates</b>. This scheme allows you the most control over where templates get instantiated and avoids code bloat.</p></dl></dl><dl class="margin"><dd><font face="Helvetica, sans-serif" size="-1" class="sans"><h5 class="HU"><i><a name="84572">-frepo</a></i></h5></font><dl class="margin"><dd><p class="Body"><a name="84573"> </a>This approach combines the simplicity of implicit instantiation with the smaller footprint obtained by instantiating templates by hand. It works by manipulating a database of template instances for each module.</p><dd><p class="Body"><a name="84583"> </a>The compiler will generate files with the extension <b class="file">.rpo</b>; these files list all the template instantiations used in the corresponding object files which could be instantiated there. The link wrapper <b class="symbol_lc">collect2</b> then updates the <b class="file">.rpo </b>files to tell the compiler where to place those instantiations and rebuilds any affected object files. The link-time overhead is negligible after the first pass, as the compiler continues to place the instantiations in the same files.</p></dl><dd><font face="Helvetica, sans-serif" size="-1" class="sans"><h5 class="HU"><i><a name="84584">Procedure</a></i></h5></font><dl class="margin"><dd><p class="Body"><a name="84585"> </a>The header file for a template must contain the template body. If template bodies are currently stored in <b class="file">.cpp</b> files, the line <b class="command">#include</b> <i class="textVariable">theTemplate</i><b class="file">.cpp</b> must be added to <i class="textVariable">theTemplate</i><b class="file">.h</b>. </p><dd><p class="Body"><a name="84586"> </a>A full build with the <b class="command">-frepo</b> option is required to create the <b class="file">.rpo</b> files that tell the compiler which templates to instantiate. The link step should be driven from <b class="command">cc</b><i class="textVariable">arch</i> rather than <b class="command">ld</b><i class="textVariable">arch</i>. </p><dd><p class="Body"><a name="84587"> </a>Subsequently individual modules can be compiled as usual (but with the <b class="command">-frepo</b> option and no other template flags). </p><dd><p class="Body"><a name="84588"> </a>When a new template instance is required the relevant part of the project must be rebuilt to update the <b class="file">.rpo</b> files. </p></dl><dd><font face="Helvetica, sans-serif" size="-1" class="sans"><h5 class="HU"><i><a name="84589">Loading Order</a></i></h5></font><dl class="margin"><dd><p class="Body"><a name="84590"> </a>The Tornado tools' dynamic linking ability requires that the module containing a symbol definition be downloaded before a module that references it. For instance, in the example below you should download <b class="file">PairA.o</b> before downloading <b class="file">PairB.o</b>. (You could also prelink them and download the linked object). </p></dl><dd><font face="Helvetica, sans-serif" size="-1" class="sans"><h5 class="HU"><i><a name="84591">Example</a></i></h5></font><dl class="margin"><dd><p class="Body"><a name="84592"> </a>This example uses a standard VxWorks BSP makefile (for concreteness, we assume a 68K target). </p></dl></dl><h4 class="EntityTitle"><a name="84593"><font face="Helvetica, sans-serif" size="-1" class="sans">Example 5-1:&nbsp;&nbsp;Sample Makefile</font></a></h4><dl class="margin"><dl class="margin"><dd><pre class="Code"><b><a name="84594">make PairA.o PairB.o ADDED_C++FLAGS=-frepo   /* dummy link step to instantiate templates */ cc68k -r -o Pair PairA.o PairB.o  /* In this case the template Pair&lt;int&gt;::Sum(void)  &nbsp;* will be instantiated in PairA.o.  &nbsp;*/  //Pair.h  template &lt;class T&gt; class Pair { public:     Pair (T _x, T _y);     T Sum ();  protected:     T x, y; };  template &lt;class T&gt; Pair&lt;T&gt;::Pair (T _x, T _y) : x (_x), y(_y) { }  template &lt;class T&gt; T Pair&lt;T&gt;::Sum () {     return x + y; }  // PairA.cpp #include "Pair.h"  int Add (int x, int y) {     Pair &lt;int&gt; Two (x, y);     return Two.Sum (); }  // PairB.cpp #include "Pair.h"  int Double (int x) { Pair &lt;int&gt; Two (x, x); return Two.Sum (); } </a></b></pre></dl></dl><a name="foot"><hr></a><p class="navbar" align="right"><a href="index.html"><img border="0" alt="[Contents]" src="icons/contents.gif"></a><a href="GuideIX.html"><img border="0" alt="[Index]" src="icons/index.gif"></a><a href="c-wfc.html"><img border="0" alt="[Top]" src="icons/top.gif"></a><a href="c-wfc1.html"><img border="0" alt="[Prev]" src="icons/prev.gif"></a><a href="c-wfc3.html"><img border="0" alt="[Next]" src="icons/next.gif"></a></p></body></html><!---by WRS Documentation (), Wind River Systems, Inc.    conversion tool:  Quadralay WebWorks Publisher 4.0.11    template:         CSS Template, Jan 1998 - Jefro --->