docs/html/WB30.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2
   3 <html>
   4 <head>
   5  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   6   <meta http-equiv="Content-Style-Type" content="text/css">
   7   <link rel="STYLESHEET" href="MakeProjectCreator.css" charset="ISO-8859-1"
   8   type="text/css">
   9
  10   <title>MPC: WB30 Project Type</title>
  11 </head>
  12
  13 <body>
  14 <div>
  15   <h1 class="Head1">WB30 Project Type documentation</h1>
  16
  17   <div>
  18     <h3 class="Head2">Background/Abstract</h3>
  19     <li class="Body">The <em>WB30 Project Type</em> generates project files
  20       utilizable by Wind River Workbench, version 3.0.  Workbench is built
  21       on the Eclipse platform and inherits many of its features.  In this
  22       document, "eclipse" is used at times to describe features common to
  23       both eclipse itself and workbench.
  24       The project type generates workbench projects from generic mpc
  25       files.  These workbench projects can then be imported into a user's
  26       workspace and built using the workbench "managed flexible build".</li>
  27
  28     <li class="Body">MPC's WB30 Project Type currently supports Linux
  29       and Windows as both host and target platforms.  It can be extended to
  30       support other platforms as well.</li>
  31   </div>
  32
  33   <div>
  34     <h3 class="Head2">Usage</h3>
  35     <p class="Body">
  36     For every <em class="Code">project <var>myprojname</var> { }</em> in mpc files, the
  37     WB30 project type
  38     generates a corresponding "workbench project" directory of the form
  39     <em class="Code">wb_<var>myprojname</var></em>.  The WB30 Project Type
  40     uses Eclipse's <em>linked resource</em> feature to work around
  41     Eclipse's usual requirement that source files reside inside the Eclipse
  42     project directory.  However, the linked resource feature also comes with
  43     restrictions; see <a href="#fullpath">the note</a> for details.
  44     </p>
  45     <h4 class="Head5">Generic workflow</h4>
  46     <p class="Body">Presuming .mpc files already exist:</p>
  47
  48     <ol>
  49       <li><p class="BodyNoLead">Generate projects using <em class="Code">-type wb30</em>.</p></li>
  50       <li><p class="BodyNoLead">Import projects into a Workbench workspace.  From within Workbench
  51         (preferably an otherwise-empty workspace) select
  52         <strong>File->Import...</strong> and perform the following actions:
  53         <ol type="a">
  54           <li><p class="Body">Choose <strong>General->Existing Projects Into
  55               Workspace</strong> and click <strong>Next</strong></p></li>
  56           <li><p class="Body">In "Select Root Directory:" text field, enter the full path
  57             to the MPC workspace.</p></li>
  58           <li><p class="Body">Workbench will scan all the subdirectories looking for existing
  59             projects.</p></li>
  60           <li><p class="Body">
  61             <strong>Be sure that the checkbox next to <em>Copy projects
  62                 into workspace</em> is <em>UN</em>checked.</strong>
  63             Copying projects into the workspace unnecessarily duplicates
  64             files, plus we have found that Workbench can get confused with file
  65             paths sometimes (though sometimes it will work).</p></li>
  66           <li><p class="Body">Click <strong>Finish</strong> to proceed with the import.</p></li>
  67         </ol>
  68         </p>
  69     </ol>
  70
  71    <h4 class="Head5">Building A Project</h4>
  72    <p class="Body">
  73    To build a project or set of projects, select the project (or
  74    projects) in the <em>Project</em> pane, then select
  75    <strong>Project->Build Project</strong>.
  76    </p>
  77 </div>
  78
  79 <div>
  80   <h3 class="Head2">Platforms and Buildspecs</h3>
  81   <p class="Body">
  82   The default platform for WB30 is called "Native" and corresponds to creating
  83   a project in Workbench using File -> New -> Native Application Project.
  84   Although this method doesn't have (in workbench) any direct support for
  85   building shared libraries, MPC does generate projects that pass the correct
  86   compiler and linker flags to create shared (dynamic) libraries.  Selecting
  87   static or shared libraries with WB30 works the same as with any other MPC
  88   project type.</p>
  89   <p class="Body">
  90   The alternative platform, "VxWorks" can be selected by passing the option
  91   <em class="Code">-value_template platform=VxWorks</em> on the mwc.pl command line.
  92   Currently the VxWorks support is inherited from the existing
  93   <em class="Code">-type wb26</em> template, so it may need some more work before it is
  94   production-ready.  Note that the wb26 template supported only DKM projects for
  95   VxWorks (Downloadable Kernel Modules).</p>
  96   <p class="Body">
  97   Each platform includes a list of supported buildspecs, and a single default
  98   buildspec.  For the "Native" platform, the list of supported buildspecs is:
  99   </p>
 100   <ul>
 101     <li><p class="Body">Linux_gnu_native_3.x_4.x</p></li>
 102     <li><p class="Body">Windows_gnu_native_3.x_4.x</p></li>
 103   </ul>
 104   <p class="Body">
 105   Users can select the list of buildspecs by passing the option
 106   <em class="Code">-value_template buildspecs=&lt;specs&gt;</em> on the mwc.pl command
 107   line, where &lt;specs&gt; is replaced by the buildspec value or values.
 108   Multiple values are separated by spaces (with the entire specs string
 109   enclosed in quotes).  Similarly, the default buildspec can be selected with
 110   <em class="Code">-value_template default_buildspec=&lt;spec&gt;</em>.</p>
 111   <p class="Body">
 112   New buildspecs (or even platforms) can be added by either editing the file
 113   <em class="Code">$MPC_ROOT/templates/wb30dll.mpt</em> (if the modification will be
 114   submitted back to the public MPC repository), or creating a file named
 115   <em class="Code">user_wb30dll.mpt</em> anywhere on the MPC -include search path.
 116   Within either of these files, create a scope for the platform/buildspec and
 117   use assignment statements within that scope to set the various template
 118   variables.  The existing buildspecs serve as the best examples.</p>
 119 </div>
 120
 121 <div>
 122 </div>
 123   <div>
 124     <h3 class="Head2">Notes</h3>
 125     <ol>
 126       <li>
 127         <p class="Body">
 128         MPC doesn't directly generate Workbench workspaces, because they depend
 129         on an unknown binary file format that it can't generate.  Instead of
 130         generating files that can be loaded as a Workbench workspace, MPC
 131         generates two files representing the workspace:
 132         </p>
 133         <ol>
 134           <li><p class="Body">wb30projects.lst</p></li>
 135           <li><p class="Body">org.eclipse.core.resources.prefs</p></li>
 136         </ol>
 137         <p class="Body">
 138         wb30projects.lst contains comment lines (starting with #) followed by
 139         one line per project, listing the full path to the .project file.<br/>
 140         org.eclipse.core.resources.prefs also begins with comment lines
 141         (starting with #) followed by the contents of one of the files from
 142         Eclipse's workspace format, specifically:
 143         <em class="Code">.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.core.resources.prefs</em>
 144         Unfortunately, this file alone is not enough to actually constitute a
 145         workspace because Eclipse uses other binary files in this .settings
 146         directory.
 147         </p>
 148       </li>
 149
 150       <li><p class="Body"><a name="fullpath"></a>WB30 uses Eclipse's <em>linked resource</em>
 151         feature to work around the usual requirement that
 152         all source code reside in Workbench project directories.  These
 153         act similar to symbolic links.  While convenient so that a
 154         developer is not required to conform to Workbench's directory
 155         layout, it comes at a price: the target of the link must be
 156         specified as a full path. The consequence of this restriction is
 157         that, once the WB30 projects get generated, the source directory can
 158         not move in the filesystem without re-generating the projects.</p></li>
 159
 160       <li><p class="Body"><a name="remove_projects"></a>MPC's WB30 Project Generator
 161         creates directories named <em class="Code">wb_*</em> for projects.
 162         To remove all WB30 projects from a
 163         directory hierarchy, on Linux you can use a command such as:</p>
 164 <blockquote>
 165 <p class="Code">$ find . -name 'wb_*' -type d | xargs rm -rf</p>
 166 </blockquote>
 167       </li>
 168
 169     </ol>
 170   </div>
 171
 172 </div>
 173
 174
 175 <hr>
 176
 177 </body> </html>