Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

update docs

Signed-off-by: Stefan Naewe <stefan.naewe@gmail.com>
  • Loading branch information...
commit a6755a30b941da7e87c11e2403e233bf1acf60d9 1 parent 564cb04
@snaewe authored
View
288 docs/html/CDT6.html
@@ -0,0 +1,288 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <meta http-equiv="Content-Style-Type" content="text/css">
+ <meta name="id" content=
+ "$Id$">
+ <link rel="STYLESHEET" href="MakeProjectCreator.css" charset="ISO-8859-1"
+ type="text/css">
+
+ <title>MPC: CDT6 Project Type</title>
+</head>
+
+<body>
+<div>
+ <h1 class="Head1">CDT6 Project Type documentation</h1>
+
+ <div>
+ <h3 class="Head2">Background/Abstract</h3>
+ <li class="body">The <em>CDT6 Project Type</em> generates project files utilizable
+ by Eclipse's CDT plugin, version 6. This is the version
+ generally available/compatible with the Eclipse "Galileo" release.
+ The project type generates eclipse projects from generic mpc
+ files. These Eclipse/CDT projects can then be imported into a user's
+ workspace and built using CDT's internal builder.</li>
+
+ <li class="body">MPC's CDT6 Project Type currently supports Linux
+ and Windows as both host and target platforms.</li>
+ </div>
+
+ <div>
+ <h3 class="Head2">Pre-requisites</h3>
+ <ul>
+ <li class="body">The following software items are required and
+ in the execution path (as well as any of their respective dependencies):
+ <dl>
+ <dt>Eclipse Galileo</dt>
+ <dd>Standard download from <a href="http://www.eclipse.org/downloads">http://www.eclipse.org/downloads</a>.</dd>
+ <dt>CDT 6.0</dt>
+ <dd>This comes packaged together with Eclipse Galileo in the
+ <a
+ href="http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/heliosr">Eclipse
+ IDE for C/C++ Development</a>.</dd>
+ <dt>Eclipse-compatible toolchain</dt>
+ <dd>On linux platforms, this should just be the standard
+ installation of the GNU toolchain for that linux distribution. On
+ Windows, Eclipse uses the <a href="http://www.mingw.org">MinGW</a>
+ toolchain, available for download. Suggested tool set is <a
+ href="http://sourceforge.net/downloads/mingw/Automated%20MinGW%20Installer/MinGW%205.1.6/MinGW-5.1.6.exe/">Automated
+ MinGW Installer</a>.</dd>
+ <dt>a compatible <tt>make</tt> tool</dt>
+ <dd>This does not need to be a full-featured GNU make, but it
+ must be in the PATH as an executable named <em>make</em>. On
+ Linux, the standard GNU make suffices. On Windows, <a
+ href="http://gnuwin32.sourceforge.net/packages/make.htm">the
+ <em>make</em> package from GNUWin32</a> is a good choice.</dd>
+ </dl>
+
+ <li class="body">The default value of 256Mb for Eclipse's Java
+ VM heap size is insufficient for building projects the size of
+ ACE/TAO/CIAO. A minimum of 768Mb or more is suggested. This can be
+ done on the command line launch of eclipse, or in the
+ <code>eclipse.ini</code> file.</li>
+
+ </ul>
+ </div>
+
+ <div>
+ <h3 class="Head2">Usage</h3>
+ For every <code>project <var>myprojname</var> { }</code> in mpc files, the CDT6 project type
+ generates a corresponding "eclipse project" directory of the form
+ <samp>cdt_<var>myprojname</var></samp>. The CDT6 Project Type
+ uses Eclipse's <em>linked resource</em> feature to work around
+ Eclipse's usual requirement that source files reside inside the Eclipse project
+ directory. However, the linked resource feature also comes with
+ restrictions; see <a href="#fullpath">the note</a> for details.
+
+ <h4>Generic workflow</h4>
+ Presuming .mpc files already exist:
+ <ol>
+ <li>Generate projects using <samp>-type cdt6</samp>.</li>
+ <li>Import projects into an Eclipse workspace.</li>
+ </ol>
+
+ <h4>Workflow for building ACE/TAO</h4>
+ <ol>
+ <li>Check out a copy of ACE/TAO.</li>
+
+ <li>Configure ACE/TAO for your target(s) by setting up
+ <samp>config.h</samp>.
+ </li>
+
+ <li>Set up environment variables (<var>ACE_ROOT</var>,
+ <var>TAO_ROOT</var>, etc.), <var>PATH</var>,
+ <var>LD_LIBRARY_PATH</var> (or similar), etc.
+ </li>
+
+ <li>Verify settings in <samp>global.features</samp> and, if changes
+ are necessary, make appropriate changes in
+ <samp>default.features</samp>.
+ </li>
+
+ <li>Generate projects using <samp>-type cdt6</samp> insuring the
+ use of <samp>mwc.pl</samp> from within ACE, e.g.,
+ <blockquote><pre>
+$ cd $TAO_ROOT
+$ mwc.pl -type cdt6 TAO_ACE.mwc
+</pre></blockquote>
+ <samp>mwc.pl</samp> will churn for awhile.
+ </li>
+
+ <li><em>Suggestion:</em> Verify that <strong>Project->Build
+ Automatically</strong> is unchecked (has no checkmark to its
+ immediate left). If this is left on, then the build will start as
+ soon as the import in the next step begins, and it will build everything.</li>
+
+ <li>From within Eclipse (preferably an otherwise-empty workspace) select
+ <strong>File->Import...</strong> and perform the following actions:
+ <ol type="a">
+ <li>Choose <strong>General->Existing Projects Into
+ Workspace</strong> and click <strong>Next</strong></li>
+ <li>In "Select Root Directory:" text field, enter the full path
+ to the directory <em>above</em> ACE, TAO, etc. (you can also use
+ the "Browse" feature to select the directory from the GUI). For
+ example, if you checked everything out into
+ <samp>/home/joedeveloper/acetao</samp> and ACE and TAO are in a
+ peer layout under that directory, you would enter
+ <samp>/home/joedeveloper/acetao</samp> in the text field.
+ </li>
+ <li>Eclipse will scan all the subdirectories looking for existing
+ projects; this can take a few minutes for something as large as
+ TAO or CIAO. <strong>NOTE:</strong> If you have previously run
+ MPC to generate CDT projects with one workspace
+ (<samp>.mwc</samp> file) and then ran it later with a different
+ workspace without removing the projects from the first
+ generation, Eclipse will still find those projects for import.
+ See <a href="#remove_projects">the note on removing generated
+ projects</a> for information on how to do that.</li>
+
+ <li><strong>Be sure that the checkbox next to <em>Copy projects
+ into workspace</em> is <em>UN</em>checked.</strong> Copying projects into
+ the workspace unnecessarily duplicates files, plus we have found
+ that Eclipse can get confused with file paths sometimes (though
+ sometimes it will work).</li>
+
+ <li>Feel free to use <em>Working Sets</em> or not. You may also
+ choose to import a subset of the discovered projects by
+ manipulating them in the list, however, experience suggests that
+ the list is ignorant of dependency interactions between projects,
+ so you must manage that manually (<em>i.e.</em>, you could import
+ a project, but not projects upon which the first depends, and
+ that first project would then fail to build).</li>
+
+ <li>Click <strong>Finish</strong> to proceed with the import.</li>
+ </ol>
+ Eclipse will now start populating the <em>Projects</em> pane with
+ projects. If you didn't uncheck <strong>Build
+ Automatically</strong>, then builds will start. Regardless, the
+ C++ indexer will run in the background across the source of all projects.</li>
+ </ol>
+
+ <h4>Building A Project</h4>
+ To build a project or set of projects, select the project (or
+ projects) in the <em>Project</em> pane, then select
+ <strong>Project->Build Project</strong>. Eclipse will evaluate
+ <em>ALL</em> dependencies automatically, though not necessarily
+ quickly.
+ <p>
+ <em>Hint:</em> a good choice to get all of ACE/TAO built is to
+ choose the <em>Naming Service</em> project.
+
+</div>
+
+<div>
+ <h3 class="Head2">Multiple Platforms</h3>
+ Just as a project created within CDT can be set up to support
+ multiple platforms, so too can projects generated via MPC. To the
+ extent possible, the platforms are represented in generated projects
+ in the same way as they are in "native" projects (though there will
+ be some differences).
+
+ <h4>Generating Projects with Multiple Platform Support</h4>
+ <p>
+ Platforms are named in a list called <samp>platforms</samp> in the
+ CDT6 template (much like other MPC templates). The list defaults to
+ the platform on which <samp>mwc.pl</samp> is run. To generate for
+ another platforms, or for additional platforms, you must provide
+ <samp>platforms</samp> with the list of platforms to generate.
+ </p>
+ <p>
+ Generate projects using a similar incantation to the default (from
+ above) using <samp>-type cdt6</samp> and <samp>-value_template
+ platform="&lt;platform_list&gt;"</samp>, insuring the
+ use of <samp>mwc.pl</samp> from within ACE, e.g.,
+ <blockquote><pre>
+$ cd $TAO_ROOT
+$ mwc.pl -type cdt6 -value_template platforms="linux cellppu" TAO_ACE.mwc
+</pre></blockquote>
+ </p>
+ <p>
+ Platforms are defined as scopes in <tt>templates/cdt6platforms.mpt</tt>.
+ </p>
+
+ <h4>Cross-Compilation</h4>
+ <p>
+ Cross-compilation is handled the same as a platform; the target is
+ the platform. If you want to generate for cross-compilation, the
+ cross-compiler information must be defined in a scope (typically
+ named for the target type) in
+ <tt>templates/cdt6platforms.mpt</tt>. If a scope does not exist for
+ the target, follow <a href="#addplatform">the instructions for adding
+ a new platform.</a>
+ </p>
+ <p>
+ In the example given above, <samp>cellppu</samp> is the name of the
+ platform for cross-compilation.
+ </p>
+
+ <h4>Adding a New Platform<a name="addplatform"></a></h4>
+ To add a new platform, particularly one for cross-compilation, it's
+ probably easiest to start from an existing scope, e.g.,
+ <samp>cellppu</samp>. For cross-compilation where the cross-compiler
+ toolchain is GNU Compiler-based, you will need to provide the names
+ of the various executables in the toolchain in the values
+ <samp>as</samp>, <samp>ar</samp>, <samp>cc</samp>, and
+ <samp>cxx</samp>. And, optionally, <samp>ccld</samp> and/or
+ <samp>cxxld</samp> if the linker used for linking C and C++
+ executables, respectively, is different from the respective
+ compiler. CDT expects these to be in the path.
+
+</div>
+ <div>
+ <h3 class="Head2">Notes</h3>
+ <ol>
+ <li>
+ There is no generated workspace. Eclipse's concept of workspace is
+ very different from MPC's, and there is no way to generate a
+ workspace. Eclipse's workspace concept doesn't permit sharing
+ among machines or developers or even checking a workspace into
+ version control.
+ </li>
+
+ <li>The Eclipse "workspace" and MPC project + source must not be in the
+ same directory hierarchy. For example, if you chose to have
+ Eclipse store its workspace in
+ <samp>/home/joedeveloper/workspace</samp>, you may not put your
+ MPC project+source under that directory. However, putting the
+ MPC project+source under <samp>/home/joedeveloper/acetao</samp>
+ or similar, <em>i.e.</em>, as a <em>peer</em> to the workspace
+ directory, is fine.
+ </li>
+
+ <li><a name="fullpath"></a>CDT6 uses Eclipse's <em>linked
+ resource</em> feature to work around the usual requirement that
+ all source code reside in Eclipse project directories. These
+ act similar to Unix symbolic links. While convenient so that a
+ developer is not required to conform to Eclipse's directory
+ layout, it comes at a price: the target of the link must be
+ specified as a full path. The consequence of this restriction is
+ that, once the CDT6 projects get generated, the source should
+ not move in the filesystem.</li>
+
+ <li><a name="remove_projects"></a>MPC's CDT Project Generator
+ creates directories named <samp>cdt_*</samp> for projects, similar
+ to how the GNUACE generator generates makefiles of the form
+ <samp>GNUmakefile.*</samp>. To remove all CDT projects from a
+ directory hierarchy, on Linux you can use a command such as:
+<pre>
+ $ find . -name 'cdt_*' -print | xargs rm -rf
+</pre>
+ </li>
+
+ <li>Perfect hash generation using the IDL compiler is not
+ currently working because the IDL compiler cannot find the
+ <samp>gperf</samp> executable. This may be a <code>PATH</code>
+ issue, "installation" issue, or an mpc file dependency issue. The
+ IDL compiler works but does not generate perfect hash lookups.</li>
+ </ol>
+ </div>
+
+</div>
+
+
+<hr>
+<address></address>
+<!-- hhmts start --> Last modified: Thu Jul 22 11:14:15 CDT 2010 <!-- hhmts end -->
+</body> </html>
View
9 docs/html/MakeProjectCreator.css
@@ -1711,3 +1711,12 @@ EM.zWhite {
vertical-align: baseline;
font-family: "Times New Roman";
}
+img.floating {
+ float: right;
+ margin: lex;
+}
+pre.codeexample {
+ font-size: 8.0 pt;
+ font-family: "courier new";
+ margin-left: 24 pt;
+}
View
537 docs/html/MakeProjectCreator.html
@@ -6,7 +6,8 @@
"HTML Tidy for Linux (vers 1 September 2005), see www.w3.org">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta http-equiv="Content-Style-Type" content="text/css">
- <meta name="GENERATOR" content="Adobe FrameMaker 7.0/HTML Export Filter">
+ <meta name="id" content=
+ "$Id$">
<link rel="STYLESHEET" href="MakeProjectCreator.css" charset="ISO-8859-1"
type="text/css">
@@ -52,8 +53,8 @@ <h3 class="Head2">Introduction</h3>
is simple and easy to use and maintain. These and other features will
be discussed in detail in the following sections. A complete example
of the use of MPC is shown in the <a href=
- "MakeProjectCreator.html#Example%20MPC%20File" class="XRef">Example
- MPC File</a> section.</li>
+ "MakeProjectCreator.html#ExampleMPCFile" class="XRef">Example MPC
+ File</a> section.</li>
</ul>
</div>
@@ -214,6 +215,29 @@ <h6 class="NumberedTableTitle">MPC Types</h6>
<tr>
<td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class="TableCode">
+ <a href="CDT6.html">cdt6</a></em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">Eclipse CDT 6 (for Eclipse "Galileo" 3.5)
+ </p></td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class="TableCode">
+ <a href="CDT6.html"><!--CDT6.html describes cdt7 as well
+ -->cdt7</a></em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">Eclipse CDT 7 (for Eclipse "Helios" 3.6)
+ </p></td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
<p class="Tbl-Body"><em class="TableCode">em3</em></p>
</td>
@@ -279,6 +303,17 @@ <h6 class="NumberedTableTitle">MPC Types</h6>
<tr>
<td rowspan="1" colspan="1">
+ <p class="TblCode"><em class="TableCode">
+ <a href="RpmSpec.html">rpmspec</a></em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">RPM packaging .spec files.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
<p class="TblCode"><em class="TableCode">sle</em></p>
</td>
@@ -330,7 +365,7 @@ <h6 class="NumberedTableTitle">MPC Types</h6>
<tr>
<td rowspan="1" colspan="1">
- <p class="TblCode">vc9</p>
+ <p class="TblCode"><em class="TableCode">vc9</em></p>
</td>
<td rowspan="1" colspan="1">
@@ -340,7 +375,7 @@ <h6 class="NumberedTableTitle">MPC Types</h6>
<tr>
<td rowspan="1" colspan="1">
- <p class="TblCode">vc10</p>
+ <p class="TblCode"><em class="TableCode">vc10</em></p>
</td>
<td rowspan="1" colspan="1">
@@ -350,7 +385,8 @@ <h6 class="NumberedTableTitle">MPC Types</h6>
<tr>
<td rowspan="1" colspan="1">
- <p class="TblCode">wb26</p>
+ <p class="TblCode"><em class="TableCode"><a href="WB26.html">
+ wb26</a></em></p>
</td>
<td rowspan="1" colspan="1">
@@ -360,6 +396,17 @@ <h6 class="NumberedTableTitle">MPC Types</h6>
<tr>
<td rowspan="1" colspan="1">
+ <p class="TblCode"><em class="TableCode"><a href="WB30.html">
+ wb30</a></em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">Wind River Workbench 3.0.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
<p class="Tbl-Body"><em class="TableCode">wix</em></p>
</td>
@@ -410,7 +457,7 @@ <h6 class="NumberedTableTitle"><a name=
<td rowspan="1" colspan="1">
<p class="Tbl-Body">This option allows the user to force
- any project to inherit from a specified base project. This
+ every project to inherit from a specified base project. This
option can be used multiple times to force multiple
inheritance upon a project.</p>
</td>
@@ -475,9 +522,8 @@ <h6 class="NumberedTableTitle"><a name=
override feature values specified in the <em class=
"Code">global.features</em> file located in the <em class=
"Code">config</em> directory. Feature files are described
- in the <a href=
- "MakeProjectCreator.html#The%20Feature%20File" class=
- "XRef">Feature File</a> section.</p>
+ in the <a href="MakeProjectCreator.html#TheFeatureFile"
+ class="XRef">Feature File</a> section.</p>
</td>
</tr>
@@ -490,7 +536,11 @@ <h6 class="NumberedTableTitle"><a name=
<td rowspan="1" colspan="1">
<p class="Tbl-Body">Specifies the feature list to set
before processing. This is a comma separated list and
- should contain no spaces.</p>
+ should contain no spaces. The -features option can be
+ used multiple times on the same command line, the
+ effect is the same as if the parameters had been
+ specified with a single -features options, with the
+ parameters joined by commas.</p>
</td>
</tr>
@@ -597,7 +647,9 @@ <h6 class="NumberedTableTitle"><a name=
<td rowspan="1" colspan="1">
<p class="Tbl-Body">This option specifies that all
generated project files will be placed in a mirrored
- directory structure.</p>
+ directory structure. If any project within the
+ workspace is referenced via a full path, use of this
+ option is likely to cause problems.</p>
</td>
</tr>
@@ -872,11 +924,12 @@ <h5 class="Head4">Additional Option Descriptions</h5>
<ul>
<li class="BodyNoLead">Some of the options in <a href=
- "MakeProjectCreator.html#84033" class="XRef">Command Line
- Options</a> require an expanded explanation. You will find more
- information on the <em class="Code">-relative</em>, <em class=
- "Code">-ti</em>, <em class="Code">-value_project</em> and
- <em class="Code">-value_template</em> options below.</li>
+ "MakeProjectCreator.html#Command%20Line%20Options" class=
+ "XRef">Command Line Options</a> require an expanded explanation.
+ You will find more information on the <em class=
+ "Code">-relative</em>, <em class="Code">-ti</em>, <em class=
+ "Code">-value_project</em> and <em class=
+ "Code">-value_template</em> options below.</li>
</ul>
<div>
@@ -942,6 +995,8 @@ <h6 class="Head5"><a name=
</div>
<div>
+ <a name="Additional -ti information"></a>
+
<h6 class="Head5">The -ti Option.</h6>
<ul>
@@ -987,6 +1042,8 @@ <h6 class="Head5">The -ti Option.</h6>
</div>
<div>
+ <a name="Additional -value_project information"></a>
+
<h6 class="Head5">The -value_project Option.</h6>
<ul>
@@ -1013,6 +1070,8 @@ <h6 class="Head5">The -value_project Option.</h6>
</div>
<div>
+ <a name="Additional -value_template information"></a>
+
<h6 class="Head5">The -value_template Option.</h6>
<ul>
@@ -1058,9 +1117,9 @@ <h6 class="Head5">Codebase Configuration File</h6>
<li class="BodyNoLead">This configuration file can be used to
specify alternate locations for the MPC Configuration File
(discussed below). If a <em class="Code">base.cfg</em> is found
- underneath the <em class="Code">config</em> directory where MPC is
- executed, it will be read to determine the location of MPC.cfg
- based on the directory in which MPC was started.</li>
+ underneath the <em class="Code">config</em> directory in the MPC
+ root directory, it will be read to determine the location of
+ MPC.cfg based on the directory in which MPC was started.</li>
<li class="Body">For example, if <em class=
"Code">$MPC_ROOT/mwc.pl</em> is run under <em class=
@@ -1083,7 +1142,16 @@ <h6 class="Head5">Codebase Configuration File</h6>
<li class="Body">You may reference environment variables, accessed
via the dollar sign (e.g., <em class="Code">$NAME</em>), on either
- side of the equals sign.</li>
+ side of the equals sign. In either this file or the MPC
+ Configuration File (see below), an alternate form of environment
+ variable reference may be used for variables which are not expected
+ to be defined in all scenarios. These variables use the syntax
+ <em class="Code">$?NAME</em> instead of <em class="Code">$NAME</em>.
+ With this syntax, if the environment variable
+ <em class="Code">NAME</em> is not defined, no error or warning is
+ printed by MPC, and the substring starting with
+ <em class="Code">$?NAME</em> until the next whitespace is expanded
+ to the empty string.</li>
</ul>
<ul>
@@ -1254,6 +1322,11 @@ <h4 class="Head3">Environment Variables</h4>
By default, the ghs type assumes that it is for Windows. Set this
environment variable prior to running MPC if this is not the
case.</li>
+
+ <li class="Body">The <em class="Code">MPC_USE_WIN_COMMANDS</em>
+ environment variable causes the Windows related pseudo template
+ variables to be used regardless of the type of project being
+ generated.</li>
</ul>
</div>
</div>
@@ -1375,6 +1448,22 @@ <h5 class="Head4">mwc and mwb</h5>
<p class="Code">&nbsp;&nbsp;}</p>
+ <p class="Code">&nbsp;</p>
+
+ <p class="Code">&nbsp;&nbsp;exclude(prop:microsoft) {</p>
+
+ <p class="Code">&nbsp;&nbsp;&nbsp;&nbsp;non_microsoft</p>
+
+ <p class="Code">&nbsp;&nbsp;}</p>
+
+ <p class="Code">&nbsp;</p>
+
+ <p class="Code">&nbsp;&nbsp;specific(rpmspec) {</p>
+
+ <p class="Code">&nbsp;&nbsp;&nbsp;&nbsp;rpm_version = 1.0</p>
+
+ <p class="Code">&nbsp;&nbsp;}</p>
+
<p class="Code">}</p>
<p class="Code">&nbsp;</p>
@@ -1393,13 +1482,16 @@ <h5 class="Head4">mwc and mwb</h5>
This information would then be included in each workspace that
inherits from it.</li>
- <li class="Body">The lines between the curly braces contain
- assignments, mpc files, directories, other workspace files or
- exclusion sections. The mpc files listed will be included in the
- workspace. If a directory is listed within the workspace, the
- workspace creator will recursively traverse that directory and
- use any mpc files that are found. If a workspace file is listed
- it will be aggregated into the main workspace.</li>
+ <li class="Body">The lines between the curly braces
+ contain assignments, mpc files, directories, other
+ workspace files or exclusion sections. For each listed item,
+ <ul>
+ <li>an mpc file will be included in the workspace</li>
+
+ <li>a directory recursively traversed and any mpc files
+ found will be included</li>
+ <li><a name="AggregatedWorkspace"></a>a workspace file will be aggregated into the main workspace.</li>
+ </ul>
<li class="Body">A workspace can have assignments interspersed
within the directories and mpc files. These assignments modify
@@ -1434,6 +1526,20 @@ <h5 class="Head4">mwc and mwb</h5>
define specific workspaces, but the MPC defaults are sufficient
for the directories involved within the workspace.</li>
+ <li class="Body"><a name="workspaceSpecific"></a>Workspaces
+ support a <em class="Code">specific</em> clause
+ conceptually and syntactically similar to <a
+ href="#projectSpecific">the project <em
+ class="Code">specific</em> clause.</a> Any variables
+ assigned within the clause are only available to
+ workspaces, not to projects. Two sorts of assignments are
+ possible: first are assignments to the keywords
+ <em class="Code">cmdline</em> and <em class="Code">implicit</em>
+ and the second are type-specific variables. Consult the
+ documentation for the type for details on type-specific variables.
+ Keyword assignments impact the entire workspace, not just the
+ <em class="Code">specific</em> scope.</li>
+
<li class="Body">Scoped assignments are assignments that are
associated with specific mpc files or directories listed with the
scope of the assignment. The following example shows a scoped
@@ -1488,10 +1594,12 @@ <h5 class="Head4">mwc and mwb</h5>
directories and mpc files from being processed. These excluded
directories and mpc files will be skipped when generating project
files and workspaces. The <em class="Code">exclude</em> keyword
- accepts project types within the parentheses (as above), which
- will cause the workspace creator to only exclude the listing for
- particular types. If no types are provided, exclusion will take
- place for all project types.</li>
+ accepts project types as well as properties (see <a href=
+ "MakeProjectCreator.html#properties" class="XRef">Properties</a>)
+ within the parentheses (as above), which will cause the workspace
+ creator to only exclude the listing for particular types. If no
+ types are provided, exclusion will take place for all project
+ types.</li>
<li class="Body">The <em class="Code">associate</em> scope
associates a name with one or more directories. This does not add
@@ -1620,6 +1728,12 @@ <h6 class="NumberedTableTitle"><a name="82186"></a>Assignment
<td rowspan="1" colspan="1">
<p class="Tbl-Body">Specifies that this project must be
built after 1 or more project names listed.</p>
+ <p class="Tbl-Body">An extended syntax is available
+ in order to associate name-value pairs with a
+ dependency: <em class="Code">&lt;project
+ name[:name=value]&gt;</em><br>
+ These name-value pairs may be used in the creation
+ of the dependencies of the project.</p>
</td>
</tr>
@@ -1655,6 +1769,21 @@ <h6 class="NumberedTableTitle"><a name="82186"></a>Assignment
<tr>
<td rowspan="1" colspan="1">
<p class="Tbl-Body"><em class=
+ "TableCode">dependent_upon</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">This keyword can only be used
+ as a header component scoped setting (ie. inside
+ the scope of Header_Files). It determines which
+ file the header file is dependent upon for vc8,
+ and vc9 only.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
"TableCode">dllout</em></p>
</td>
@@ -2073,6 +2202,25 @@ <h6 class="NumberedTableTitle"><a name="82186"></a>Assignment
<li class="BodyNoLead">Assignments can also use the <em class=
"Code">+=</em> and <em class="Code">-=</em> operators to add
and subtract values from keyword values.</li>
+
+ <li class="Body">Assignments can be bracketed by curly braces
+ so they can span multiple lines. The opening curly brace must
+ be the last thing on the same line as the operator and the closing
+ brace must be on its own line (but can have leading white space).
+ Optionally, \n, \s, or \ns can be included after the operator. These
+ indicate that new lines should be retained (\n) and leading white space
+ should be retained (\s).</li>
+
+ <li style="list-style: none">
+ <p class="Code">&nbsp;</p>
+ <p class="Code">specific(rpmspec) {</p>
+ <p class="Code">&nbsp;rpm_description = \ns {</p>
+ <p class="Code">This description</p>
+ <p class="Code">spans multiple lines.</p>
+ <p class="Code">&nbsp;}</p>
+ <p class="Code">}</p>
+ <p class="Code">&nbsp;</p>
+ </li>
<li class="Body">If a <em class="Code">sharedname</em> is
specified in the mpc file and <em class="Code">staticname</em>
@@ -2108,6 +2256,8 @@ <h6 class="NumberedTableTitle"><a name="82186"></a>Assignment
</div>
<div>
+ <a name="16907"></a>
+
<h6 class="Head5">Components</h6>
<ul>
@@ -2248,6 +2398,8 @@ <h6 class="NumberedTableTitle">Component Names and Default
within named blocks.</li>
<li style="list-style: none">
+ <a name="MPC grouping example"></a>
+
<p class="Code">&nbsp;</p>
<p class="Code">Source_Files(MACRO_NAME) {</p>
@@ -2372,7 +2524,7 @@ <h6 class="Head5">Expand Clause</h6>
</div>
<div>
- <h6 class="Head5">Specific Clause</h6>
+ <h6 class="Head5"><a name="projectSpecific">Specific Clause</a></h6>
<ul>
<li class="BodyNoLead">The <em class="Code">specific</em>
@@ -2414,8 +2566,13 @@ <h6 class="Head5">Specific Clause</h6>
(see <a href="MakeProjectCreator.html#Command%20Line%20Options"
class="XRef">Command Line Options</a>).</li>
+ <a name="properties">
<li class="Body">The following table shows which properties
- apply to which project types.</li>
+ apply to which project types. The <em class="Code">static</em>
+ property (not represented in the table) is set if the -static
+ option is supplied when processing the project files.
+ Additionally, a property that corresponds to the language
+ will be set (e.g., cplusplus, csharp, java, vb).</li>
<li class="Body">
<h6 class="NumberedTableTitle"><a name=
@@ -2882,6 +3039,8 @@ <h6 class="Head5">Conditional Clause</h6>
</div>
<div>
+ <a name="Custom Types and Build Rules"></a>
+
<h6 class="Head5">Custom Types and Build Rules</h6>
<ul>
@@ -2947,11 +3106,19 @@ <h6 class="Head5">Custom Types and Build Rules</h6>
<em class="Code">MOC_Files</em> can be used to specify the
input files for this new file type.</li>
+ <li class="Body">Define_Custom definitions may use single
+ inheritance. This is useful for creating aliased names:
+ <p class="Code">Define_Custom(QtMOC) : MOC {</p>
+ <p class="Code">}</p>
+ </li>
+
<li class="Body">The following table contains the keywords that
can be used within the scope of <em class=
"Code">Define_Custom</em>.</li>
<li style="list-style: none">
+ <a name="32899"></a>
+
<h6 class="NumberedTableTitle">Define_Custom Keywords</h6>
<table border="1" summary="Define_Custom Keywords">
@@ -3043,6 +3210,25 @@ <h6 class="NumberedTableTitle">Define_Custom Keywords</h6>
<tr>
<td rowspan="1" colspan="1">
<p class="Tbl-Body"><em class=
+ "TableCode">dependent_libs</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">If this is given a value, then a dependency upon that
+ library value will be given to all of the generated files.
+ The format for this entry should be the basename for the
+ library (no library prefix, postfix, or extension)
+ preceded by any relative or absolute path to the library.
+ The typical use for this would be so that a project is
+ rebuilt when a library needs to be rebuilt for its
+ dependent executable. The default for this is unset and no
+ dependency will be generated.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
"TableCode">inputext</em></p>
</td>
@@ -3760,8 +3946,8 @@ <h6 class="NumberedTableTitle">Define_Custom Keywords</h6>
keywords that can be used within the custom file type component
lists: <em class="Code">command</em>, <em class=
"Code">commandflags</em>, <em class="Code">dependent</em>,
- <em class="Code">gendir</em>, <em class=
- "Code">postcommand</em>, and <em class=
+ <em class="Code">dependent_libs</em>, <em class="Code">gendir</em>,
+ <em class="Code">postcommand</em>, and <em class=
"Code">recurse</em>.</li>
<li class="Body">The <em class="Code">recurse</em> keyword
@@ -3769,7 +3955,8 @@ <h6 class="NumberedTableTitle">Define_Custom Keywords</h6>
class="XRef">Assignment Keywords</a>.</li>
<li class="Body">The <em class="Code">command</em>, <em class=
- "Code">commandflags</em>, <em class="Code">dependent</em> and
+ "Code">commandflags</em>, <em class="Code">dependent</em>,
+ <em class="Code">dependent_libs</em> and
<em class="Code">postcommand</em> keywords can be used to
augment or override the value defined in the <em class=
"Code">Define_Custom</em> section.</li>
@@ -4431,6 +4618,18 @@ <h6 class="NumberedTableTitle"><a name=
<tr>
<td rowspan="1" colspan="1">
<p class="TblCode"><em class=
+ "TableCode">&lt;%pathsep%&gt;</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">A platform non-specific path
+ separator (; or :).</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="TblCode"><em class=
"TableCode">&lt;%or%&gt;</em></p>
</td>
@@ -4455,6 +4654,18 @@ <h6 class="NumberedTableTitle"><a name=
<tr>
<td rowspan="1" colspan="1">
<p class="TblCode"><em class=
+ "TableCode">&lt;%prj_type%&gt;</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The project type as supplied
+ by the -type command line option.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="TblCode"><em class=
"TableCode">&lt;%quote%&gt;</em></p>
</td>
@@ -4513,6 +4724,51 @@ <h6 class="NumberedTableTitle"><a name=
variable setting.</p>
</td>
</tr>
+
+ <tr>
+ <td rowspan="1" colspan="2">
+ <p class="TblCode">The following variables will
+ be set to the known extension for Windows based
+ project types and empty on non-Windows based
+ project types.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="TblCode"><em class=
+ "TableCode">&lt;%bat%&gt;</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The extension for batch
+ files.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="TblCode"><em class=
+ "TableCode">&lt;%cmd%&gt;</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The extension for command
+ files.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="TblCode"><em class=
+ "TableCode">&lt;%exe%&gt;</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The extension for executable
+ files.</p>
+ </td>
+ </tr>
</table>
</li>
</ul>
@@ -4521,6 +4777,8 @@ <h6 class="NumberedTableTitle"><a name=
</div>
<div>
+ <a name="TheFeatureFile" id="TheFeatureFile"></a>
+
<h5 class="Head4">The Feature File</h5>
<ul>
@@ -4864,6 +5122,8 @@ <h5 class="Head4">Custom Defined Files</h5>
</div>
<div>
+ <a name="ExampleMPCFile" id="ExampleMPCFile"></a>
+
<h5 class="Head4">Example MPC File</h5>
<ul>
@@ -5183,11 +5443,11 @@ <h5 class="Head4"><a name="MPD Syntax"></a>Template Files
<p class="Code">&nbsp;</p>
</li>
- <li class="Body">A <em class="Code">foreach</em> statement can
- also appear on a single line or can span multiple lines. As
- described below in the keywords section, the <em class=
- "Code">foreach</em> statement evaluates the variable in a
- space-separated list context.</li>
+ <li class="Body"><a name="foreach syntax"></a> A <em class=
+ "Code">foreach</em> statement can also appear on a single line or
+ can span multiple lines. As described below in the keywords
+ section, the <em class="Code">foreach</em> statement evaluates
+ the variable in a space-separated list context.</li>
<li class="Body">There are a couple of ways to write a <em class=
"Code">foreach</em> loop. The first and preferred way is to name
@@ -5241,6 +5501,8 @@ <h5 class="Head4"><a name="MPD Syntax"></a>Template Files
appear in template files.</li>
<li style="list-style: none">
+ <a name="38037"></a>
+
<h6 class="NumberedTableTitle">Template File Keywords</h6>
<table border="1" summary="Template File Keywords">
@@ -5321,6 +5583,19 @@ <h6 class="NumberedTableTitle">Template File Keywords</h6>
<tr>
<td rowspan="1" colspan="1">
<p class="Tbl-Body"><em class=
+ "TableCode">deref</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">Dereference the variable passed as
+ a parameter, treating its value as another variable
+ name and returning that variable's value.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
"TableCode">dirname</em></p>
</td>
@@ -5404,8 +5679,8 @@ <h6 class="NumberedTableTitle">Template File Keywords</h6>
<td rowspan="1" colspan="1">
<p class="Tbl-Body">This is similar to eval in perl. The
- template code passed to this function will be evaluated
- within the context of the current template.</p>
+ template variable passed to this function will be
+ evaluated within the context of the current template.</p>
</td>
</tr>
@@ -5634,15 +5909,21 @@ <h6 class="NumberedTableTitle">Template File Keywords</h6>
<td rowspan="1" colspan="1">
<p class="Tbl-Body">This function will remove a file in a
- component list. It requires two parameters. The first
- parameter is a component name(e.g., Source_Files) and the
- second parameter is a project or template variable name.
- The third and fourth optional parameters allow you to
- alter the project or template variable value in order to
- remove files that do not match the value exactly. The
- third parameter is a regular expression and the fourth
- parameter is the value with which to replace the regular
- expression match.</p>
+ component list. It requires three parameters. The first
+ parameter is a component name (e.g., Source_Files), the
+ second parameter is a regular expression pattern and
+ the third parameter is a project or template variable
+ name. The fourth and optional parameter allows you to
+ alter the project or template variable value by
+ removing the end matching portion. If the value of
+ the project or template variable (i.e., parameter
+ three) after being modified by parameter four and
+ having the regular expression pattern (i.e.,
+ parameter two) appended to it matches any value
+ within the compent list (named by parameter one), it
+ will be removed from that component list and passed
+ back.
+ any </p>
</td>
</tr>
@@ -5671,8 +5952,22 @@ <h6 class="NumberedTableTitle">Template File Keywords</h6>
Currently, the only function name supported is "escape".
The third parameter specifies a string on which the
function will operate. Any template text that matches the
- string parameter will be transformed by the function
- parameter. A scope is then ended by passing "leave".</p>
+ string parameter while within this scope will be
+ transformed by the function parameter. A scope is then
+ ended by passing "leave".</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class="TableCode">set</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">This function is used to set or
+ create a template variable. This function takes two
+ parameters; the first is the template variable name
+ and the second is the variable value.</p>
</td>
</tr>
@@ -5716,6 +6011,22 @@ <h6 class="NumberedTableTitle">Template File Keywords</h6>
<tr>
<td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class="TableCode">translate_vars</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The first parameter to this function
+ is the name of a variable. The second, optional,
+ parameter is the operating system for which the
+ project is being generated (e.g., linux, solaris,
+ win32, etc.) It replaces $(...) found within the
+ value of the variable with the equivalent environment
+ variable reference based on the operating system.</p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
<p class="Tbl-Body"><em class="TableCode">uc</em></p>
</td>
@@ -6050,6 +6361,8 @@ <h6 class="Head5"><a name="Document Template Script"></a>
</ul>
<div>
+ <a name="Custom Types"></a>
+
<h6 class="Head5">Custom Types</h6>
<ul>
@@ -6228,6 +6541,112 @@ <h6 class="NumberedTableTitle">Custom Type Fields</h6>
<p class="Code">&nbsp;</p>
</li>
+
+ <li class="Body">Certain project types don't support the same
+ input file used by multiple custom types (current examples of
+ this are vc10, cdt6, and cdt7). To accomodate these types, MPC
+ has a capability called "combined custom". With this capability
+ enabled in the specific ProjectCreator, MPC will "fold together"
+ the multiple custom steps so that the target tool (Visual Studio
+ or Eclipse CDT) sees it as a single custom step that happens to
+ run two or more commands. When "combined custom" is enabled,
+ the template needs to be written for it by checking if
+ <em class="Code">custom_type-&gt;input_file-&gt;commands</em> is
+ non-empty. If it isn't empty, the values in it can be iterated
+ over with a <em class="Code">&lt;%foreach%&gt;</em>. During that
+ iteration, the following values can be obtained by the template.
+ Each one would appear in the template preceeded by
+ <em class="Code">custom_type-&gt;input_file-&gt;</em></li>
+
+ <li style="list-style: none">
+ <h6 class="NumberedTableTitle">Custom Type Fields for Combined
+ Custom</h6>
+ <table border="1"
+ summary="Custom Type Fields for Combined Custom">
+ <tr>
+ <th rowspan="1" colspan="1">
+ <p class="Tbl-Heading">Value</p>
+ </th>
+
+ <th rowspan="1" colspan="1">
+ <p class="Tbl-Heading">Description</p>
+ </th>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
+ "TableCode">command</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The effective command, taking into
+ account the <em class="TableCode">flag_overrides</em>.
+ </p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
+ "TableCode">command-&gt;outopt</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The <em class=
+ "TableCode">output_option</em> for this particular
+ command, taking into account the
+ <em class="TableCode">flag_overrides</em>.
+ </p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
+ "TableCode">command-&gt;outfile</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The first output file for this
+ particular command (for use with
+ <em class="TableCode">outopt</em>).
+ </p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
+ "TableCode">command-&gt;flags</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The <em class=
+ "TableCode">commandflags</em> for this particular
+ command, taking into account the
+ <em class="TableCode">flag_overrides</em>.
+ </p>
+ </td>
+ </tr>
+
+ <tr>
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body"><em class=
+ "TableCode">command-&gt;gdir</em></p>
+ </td>
+
+ <td rowspan="1" colspan="1">
+ <p class="Tbl-Body">The <em class=
+ "TableCode">gendir</em> for this particular
+ command.
+ </p>
+ </td>
+ </tr>
+
+ </table>
+ </li>
+
</ul>
</div>
@@ -6295,9 +6714,9 @@ <h6 class="NumberedTableTitle">Grouped Files Field Names</h6>
variable cannot be named as stated <a href=
"MakeProjectCreator.html#foreach%20syntax" class=
"XRef">previously</a>. The following example involves source
- files, but any of the components listed in <a href=
- "MakeProjectCreator.html#16907" class="XRef">the mpc and mpb
- section</a> can be used.</li>
+ files, but any of the <a href="MakeProjectCreator.html#16907"
+ class="XRef">components</a> listed in the mpc and mpb section
+ can be used.</li>
<li style="list-style: none">
<p class="Code">&nbsp;</p>
@@ -6661,7 +7080,7 @@ <h5 class="Head4">Template</h5>
<p class="Code">// Section 13 - BIN DIRECTORY</p>
<p class="Code">
- &lt;%if(install)%&gt;&lt;%install%&gt;&lt;%else%&gt;.&lt;%endif%&gt;</p>
+ &lt;%if(exeout)%&gt;&lt;%exeout%&gt;&lt;%else%&gt;.&lt;%endif%&gt;</p>
<p class="Code">&nbsp;</p>
View
201 docs/html/RpmSpec.html
@@ -0,0 +1,201 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <meta http-equiv="Content-Style-Type" content="text/css">
+ <meta name="id" content=
+ "$Id$">
+ <link rel="STYLESHEET" href="MakeProjectCreator.css" charset="ISO-8859-1"
+ type="text/css">
+
+ <title>MPC: RpmSpec Type</title>
+</head>
+
+<body>
+<div>
+ <h1 class="Head1">RpmSpec Type documentation</h1>
+
+ <div>
+ <h3 class="Head2">Background/Abstract</h3>
+ <ul>
+ <li class="body">The <em>RpmSpec Type</em> generates
+ <samp>.spec</samp> files suitable for use by the <samp><a
+ href="http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-rpmbuild.html">rpmbuild</a></samp>
+ utility to build and package. It additionally creates a Bourne
+ shell script that automates creation of source tarball and proper
+ dependency-order building/packaging of <samp>.spec</samp> files.
+ </li>
+
+ <li class="body">The RpmSpec type refines the existing
+ <em>aggregated workspace</em> MPC concept, as well as introduces
+ the ability to have <samp>specific</samp> clauses inside
+ workspace declarations (<samp>.mwc</samp> files). Consequently,
+ workspace files utilizing these new features are not
+ backwards-compatible with prior releases of MPC.</li>
+
+ <li class="body">Since RPM is primarily Linux-based, RpmSpec only
+ officially supports use on Linux-based systems. It <em>may</em>
+ work on platforms for which an RPM port exists, but such success
+ would be coincidental and neither intended, tested, nor
+ guaranteed.</li>
+ </ul>
+ </div>
+
+ <div>
+ <h3 class="Head2">Pre-requisites</h3>
+ <ul>
+ <li class="body">The following software items are required and
+ in the execution path (as well as any of their respective dependencies):
+ <dl>
+ <dt>RPM</dt>
+ <dd>Minimum of version 4.7.1 recommended (not tested with
+ other versions).</dd>
+ <dt>Development toolchain</dt>
+ <dd>This can be the standard development toolchain. Packaging
+ for other architectures is supported if the toolchain in the path
+ is a cross-compiler for that architecture.</dd>
+ </dl>
+ </ul>
+ </div>
+
+ <div>
+ <h3 class="Head2">Usage</h3>
+ The RpmSpec type refines an existing concept in MPC known as
+ <em><a
+ href="MakeProjectCreator.html#AggregatedWorkspace">aggregate
+ workspaces</a></em> to define package scopes. When
+ <code>mwc.pl</code> is run on a top-level workspace with
+ <code>-type rpmspec</code>, each aggregated workspace is presumed
+ to define the scope of a package that will become an RPM.
+ Inter-project dependencies that exist between any projects known to
+ the top-level workspace automatically turn into inter-package
+ dependencies in RPMs.
+
+ <h4>Generic workflow</h4>
+ <div align="center">
+ <img src="rpmworkflow.png" alt="rpm workflow"/>
+ <h6 align="center">Figure: RPM Workflow</h6>
+ </div>
+ Presuming <code>.mwc</code> files already exist, and that
+ inter-project dependencies are complete and well-formed (i.e.,
+ contain sufficient <samp>after</samp> statements to insure proper
+ build ordering):
+ <ol>
+ <li>Use the command <samp>mwc.pl -type rpmspec <em>top-level-workspace.mwc</em></samp> to generate
+ <code>.spec</code> files and <samp>*_rpm.sh</samp> builder script.</li>
+
+ <li>Run the <code><em>top-level-workspace</em>_rpm.sh</code>
+ script to build/package.</li>
+ </ol>
+ </div>
+
+ <div>
+ <h3 class="Head2">Adapting/Writing Projects for Packaging</h3>
+ <h4><a name="mwcnotes"></a>Creating Workspaces</h4>
+ <p>The RpmSpec type uses <a
+ href="MakeProjectCreator.html#AggregatedWorkspace">aggregate
+ workspaces</a> to define the scope of a package. In other words,
+ defining a package involves writing a <samp>.mwc</samp> file that
+ includes all the projects that should go into that package.
+ An additional <samp>.mwc</samp> file must be written for each
+ additional package. Finally, these <em>package</em> workspaces get
+ aggregated into a workspace.
+
+ <p>RPM packages require extra information not needed by "normal"
+ MPC projects or workspaces. This information is defined in a
+ <samp>specific</samp> clause in the workspace for the
+ <samp>rpmspec</samp> type, e.g.,
+
+ <pre class="codeexample">
+// top-level workspace
+workspace {
+ specific (rpmspec) {
+ rpm_version = 1.0
+ rpm_release = 1
+ }
+ package1.mwc
+ package2.mwc
+}
+</pre>
+ Details on the variables allowed in the <samp>specific</samp>
+ clause can be found in the <a href="../templates/rpmspec.txt">
+ <samp>$MPC_ROOT/docs/templates/rpmspec.txt</samp></a> file.
+
+ <p>If you use workspaces as a part of
+ building right now, you may wish to write additional
+ workspace files specifically for packaging via RPM.
+
+ <h4><a name="installready"></a>Making Projects
+ <em>Install-Ready</em></h4>
+
+ MPC-assisted packaging requires some attention from the developer
+ in order to yield its full potential. What this means is that in
+ order for a project to avail itself to be packaged, it must take
+ care to insure that any collateral (such as files) that it needs to
+ end up in the package get installed via MPC's <em>install</em> feature.
+ Note that this feature is currently only implemented within the
+ <samp>gnuace</samp> project type.
+
+ Typically, this involves inheriting from the <samp>install</samp>
+ base project in order to enable auto-generation of installation
+ rules in the makefiles. MPC defaults to making educated guesses as
+ to what files should be installed (e.g., for an <samp>exe</samp>
+ project, it figures that the executable should be installed), but a
+ developer can augment or replace MPC's guesses using
+ <samp>Install*_Files</samp> groupings. See the documentation on
+ the <samp>gnuace</samp> installation feature for details.
+ </div>
+</div>
+
+<div>
+ <h3 class="Head2">Notes</h3>
+ <h4><a name="rpmnotes"></a>Notes on Generated RPMs</h4>
+ <ol>
+ <li>RPMs are relocatable using the <code>--prefix</code> or
+ <code>--relocate</code> options to <code>rpm</code>.</li>
+ <li>The RpmSpec type has no control over where the RPM system performs
+ it's "work" (building, staging,
+ packaging, etc.). In the
+ past, this was often <samp>/usr/src/redhat</samp>, though your
+ system may be configured differently.<br/><samp>rpmbuild</samp>
+ holds this directory in its <em>_topdir</em> configuration
+ variable. To see the value of <em>_topdir</em> on
+ your system, execute the following command:<br/>
+ <pre class="codeexample">
+<b>$ rpmbuild --showrc | grep '_topdir[^}]'</b>
+-14: _topdir %{getenv:HOME}/rpmbuild
+</pre>
+ </li>
+
+ <li>Binary RPMs land in <samp><em>_topdir</em>/RPMS</samp>.</li>
+ <li>Source RPMs land in <samp><em>_topdir</em>/SRPMS</samp>.</li>
+ </ol>
+
+ <h4><a name="scriptnotes"></a>Notes on Generated Script</h4>
+ <ol>
+ <li>The script takes one optional argument
+ indicating the architecture for which it should create packages.
+ The script makes no attempt to "find" a toolchain for that
+ architecture, instead presuming that whatever toolchain is
+ needed can be found in the PATH or is specified in the
+ <code>.spec</code> file.</li>
+
+ <li>The script performs a build/install activity for each package.
+ Installation is not into the running system, but rather into a
+ "fake" area. Installation is necessary to satisfy inter-package
+ dependency requirements.<br/>The location of the "fake" area
+ defaults to <samp>/tmp/mpcrpm</samp> but can be changed by setting the
+ <samp>&lt;%rpm_mpc_temp%&gt;</samp> in a workspace
+ <samp>specific</samp> clause, typically in the top-level
+ workspace.</li>
+
+
+ </ol>
+</div>
+
+
+
+<hr>
+<!-- hhmts start --> Last modified: Fri Jan 14 09:09:04 CST 2011 <!-- hhmts end -->
+</body> </html>
View
133 docs/html/WB26.html
@@ -0,0 +1,133 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <meta http-equiv="Content-Style-Type" content="text/css">
+ <meta name="id" content=
+ "$Id$">
+ <link rel="STYLESHEET" href="MakeProjectCreator.css" charset="ISO-8859-1"
+ type="text/css">
+
+ <title>MPC: WB26 Project Type</title>
+</head>
+
+<body>
+<div>
+ <h1 class="Head1">WB26 Project Type documentation</h1>
+
+ <div>
+<p>
+Starting with ACE/TAO x.6.3 it is possible to generate project files
+for the WindRiver Workbench version 2.6 (VxWorks 6.4). We have validated
+the MPC support for the ACE lib, TAO libs and the TAO tests.
+</p>
+<p>With VxWorks we have to do a cross build. The first step is to setup a host
+build, from this host build we use the gperf and TAO_IDL tools
+in the cross build.
+</p>
+<p>The Workbench is using eclipse as framework and then has several
+WindRiver specific extensions. Part of the generation done by
+MPC is then specifically for the WindRiver tools, part is for the
+eclipse environment. The Workbench uses the fixed project filenames
+<code>.project</code>, <code>.wrproject</code>, and <code>.wrmakefile</code>.
+In the <code>.project</code> file the files in the project are listed,
+in the <code>.wrproject</code> the compiler and linker flags are
+defined, and in the <code>.wrmakefile</code> the custom build rules
+are defined, like triggering the IDL compiler.</p>
+<p>By default the files are generated in the same directory as the MPC file.
+When you have multiple projects in one directory you have to add
+<code>-make_coexistence</code> to the invocation of <code>mwc.pl</code>
+Then for each project a new subdirectory will be created to
+store the files the workbench needs. If you run <code>mwc.pl -make_coexistence</code> from the
+ACE_wrappers directory you will get a lot of subdirectories in your tree.
+</p>
+By default we generate for the flexible build support, when you want to use
+standard build use <code>-value_template standard_build=1</code>.
+</p>
+<p>
+To get a project with all dependencies create a new workspace file, f.e. vxworks.mwc
+<pre>
+workspace(vxworks) {
+ ace
+ TAO/tao
+ TAO/tests/Hello
+}
+</pre>
+</p>
+<p>
+You should generate the project files
+from a VxWorks development shell or should have executed the wrenv script. With x.6.4 or newer
+you do execute:
+<pre>
+set ACE_ROOT=your_path
+cd %ACE_ROOT%
+perl %ACE_ROOT%\bin\mwc.pl vxworks.mwc -type wb26 -make_coexistence
+</pre>
+</p>
+<p>
+After you have generated the project files you have to import them
+into your current Workbench workspace with the following steps
+<itemize>
+<item>Open the workbench</item>
+<item>Select File, Import, General, Existing Projects into Workspace</item>
+<item>Select your ACE_ROOT directory and let the Workbench search for projects</item>
+<item>Select now the projects you want to import in the Projects list and select Finish</item>
+<item>After importing close the workbench</item>
+<item>Copy the prefs file to its location, see below</item>
+<item>Start the workbench again</item>
+</itemize>
+</p>
+<p>The build order of the projects is stored in an eclipse file that
+is generated as workspace by the <code>wb26</code> generator. After
+you have imported the projects into the Workbench close it and then
+copy the generated <code>org.eclipse.core.resources.prefs</code> file to
+the <code>.metadata\.plugins\org.eclipse.core.runtime\.settings</code>
+directory of the Workbench and then restart the workbench again. Do note
+that the build order can only be generated for the projects that are listed
+in the MPC workspace. The other option is to use subprojects to which
+you can enable with <code>-value_template enable_subprojects=1</code>. There is a bug
+in Workbench 2.6/3.0 related to the build order, it is ignored if you use
+<code>wrws_update</code> to build the workspace from the commandline.</p>
+<p>When compiling TAO you need to have tao_idl and gperf available. You can copy tao_idl and
+gperf manually to the ACE_wrappers\bin directory of your target build or you can specify an
+alternative tao_idl when generating the workspace like below.
+<pre>
+perl %ACE_ROOT%\bin\mwc.pl vxworks.mwc -type wb26 -value_template tao_idl=$(HOST_TAO_IDL)
+perl %ACE_ROOT%\bin\mwc.pl vxworks.mwc -type wb26 -value_template tao_idl=c:\tmp\tao_idl
+</pre>
+</p>
+<p>When using the <code>-expand_vars</code> by default only the environment variables which match
+the wildcard <code>*_ROOT</code> are expanded. If you want to get other environment variables expanded (like <code>WIND_BASE</code>)
+you can specify these through the <code>-relative</code> argument or use a file that you specify with <code>
+-relative_file</code>. For example you can use the following relative_file which expands the environment variables
+listed.
+<pre>
+*_ROOT
+TAO_ROOT, $ACE_ROOT/TAO
+CIAO_ROOT, $TAO_ROOT/CIAO
+*_BASE
+</pre>
+</p>
+<p>
+We do have some limitations at this moment because of restrictions in MPC or the Workbench. We are working
+on resolving the MPC restrictions, the Workbench restrictions have been reported to WindRiver and are already
+converted to enhancement requests. It is important to get these enhancement requests implemented by
+WindRiver. As user you can have impact on the importancy of these enhancement requests, create a new TSR
+for WindRiver and ask WindRiver to implement these enhancement requests. Pleas let us know that you have
+done this so that we can inform our local WindRiver contacts. We also have a large list of POSIX enhancement
+requests, if you are interested in more POSIX compliance contact us to get this list.
+<itemize>
+<item>You need to close the workbench when generating the project files. The WB doesn't detect that the .project/.wrproject/org.eclipse.core.resources.prefs files got changed on disk (WIND00116553)</item>
+<item>You need to import, close, and then change the build order file (WIND00116553)</item>
+<item>When using includes/recursive_includes do not use . as path, but an environment variable which can be expanded to a full path (combined WB/MPC restriction)</item>
+<item>We need to generate full paths in the .project file because WB doesn't support relative files like ../MyHeader.h (WIND00116641)</item>
+<item>There is no dependency between the IDL file and the resulting *C.{h,cpp,inl} and *S.{h,cpp,inl} files. This is because the IDL compiler
+can't be integrated a real build tool because a custom clean step can't be defined (WIND00117037)</item>
+</itemize>
+</p>
+
+</div>
+<hr>
+
+</body> </html>
View
164 docs/html/WB30.html
@@ -0,0 +1,164 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <meta http-equiv="Content-Style-Type" content="text/css">
+ <meta name="id" content=
+ "$Id$">
+ <link rel="STYLESHEET" href="MakeProjectCreator.css" charset="ISO-8859-1"
+ type="text/css">
+
+ <title>MPC: WB30 Project Type</title>
+</head>
+
+<body>
+<div>
+ <h1 class="Head1">WB30 Project Type documentation</h1>
+
+ <div>
+ <h3 class="Head2">Background/Abstract</h3>
+ <li class="body">The <em>WB30 Project Type</em> generates project files
+ utilizable by Wind River Workbench, version 3.0. Workbench is built
+ on the Eclipse platform and inherits many of its features. In this
+ document, "eclipse" is used at times to describe features common to
+ both eclipse itself and workbench.
+ The project type generates workbench projects from generic mpc
+ files. These workbench projects can then be imported into a user's
+ workspace and built using the workbench "managed flexible build".</li>
+
+ <li class="body">MPC's WB30 Project Type currently supports Linux
+ and Windows as both host and target platforms. It can be extended to
+ support other platforms as well.</li>
+ </div>
+
+ <div>
+ <h3 class="Head2">Usage</h3>
+ For every <code>project <var>myprojname</var> { }</code> in mpc files, the
+ WB30 project type
+ generates a corresponding "workbench project" directory of the form
+ <samp>wb_<var>myprojname</var></samp>. The WB30 Project Type
+ uses Eclipse's <em>linked resource</em> feature to work around
+ Eclipse's usual requirement that source files reside inside the Eclipse
+ project directory. However, the linked resource feature also comes with
+ restrictions; see <a href="#fullpath">the note</a> for details.
+
+ <h4>Generic workflow</h4>
+ Presuming .mpc files already exist:
+ <ol>
+ <li>Generate projects using <samp>-type wb30</samp>.</li>
+ <li>Import projects into a Workbench workspace. From within Workbench
+ (preferably an otherwise-empty workspace) select
+ <strong>File->Import...</strong> and perform the following actions:
+ <ol type="a">
+ <li>Choose <strong>General->Existing Projects Into
+ Workspace</strong> and click <strong>Next</strong></li>
+ <li>In "Select Root Directory:" text field, enter the full path
+ to the MPC workspace.</li>
+ <li>Workbench will scan all the subdirectories looking for existing
+ projects.</li>
+ <li><strong>Be sure that the checkbox next to <em>Copy projects
+ into workspace</em> is <em>UN</em>checked.</strong>
+ Copying projects into the workspace unnecessarily duplicates
+ files, plus we have found that Workbench can get confused with file
+ paths sometimes (though sometimes it will work).</li>
+ <li>Click <strong>Finish</strong> to proceed with the import.</li>
+ </ol>
+ </ol>
+
+ <h4>Building A Project</h4>
+ To build a project or set of projects, select the project (or
+ projects) in the <em>Project</em> pane, then select
+ <strong>Project->Build Project</strong>.
+
+</div>
+
+<div>
+ <h3 class="Head2">Platforms and Buildspecs</h3>
+ The default platform for WB30 is called "Native" and corresponds to creating
+ a project in Workbench using File -> New -> Native Application Project.
+ Although this method doesn't have (in workbench) any direct support for
+ building shared libraries, MPC does generate projects that pass the correct
+ compiler and linker flags to create shared (dynamic) libraries. Selecting
+ static or shared libraries with WB30 works the same as with any other MPC
+ project type.<p/>
+ The alternative platform, "VxWorks" can be selected by passing the option
+ <code>-value_template platform=VxWorks</code> on the mwc.pl command line.
+ Currently the VxWorks support is inherited from the existing
+ <code>-type wb26</code> template, so it may need some more work before it is
+ production-ready. Note that the wb26 template supported only DKM projects for
+ VxWorks (Downloadable Kernel Modules).<p/>
+ Each platform includes a list of supported buildspecs, and a single default
+ buildspec. For the "Native" platform, the list of supported buildspecs is:
+ <ul>
+ <li>Linux_gnu_native_3.x_4.x</li>
+ <li>Windows_gnu_native_3.x_4.x</li>
+ </ul>
+ Users can select the list of buildspecs by passing the option
+ <code>-value_template buildspecs=&lt;specs&gt;</code> on the mwc.pl command
+ line, where &lt;specs&gt; is replaced by the buildspec value or values.
+ Multiple values are separated by spaces (with the entire specs string
+ enclosed in quotes). Similarly, the default buildspec can be selected with
+ <code>-value_template default_buildspec=&lt;spec&gt;</code>.<p/>
+ New buildspecs (or even platforms) can be added by either editing the file
+ <code>$MPC_ROOT/templates/wb30dll.mpt</code> (if the modification will be
+ submitted back to the public MPC repository), or creating a file named
+ <code>user_wb30dll.mpt</code> anywhere on the MPC -include search path.
+ Within either of these files, create a scope for the platform/buildspec and
+ use assignment statements within that scope to set the various template
+ variables. The existing buildspecs serve as the best examples.</p>
+</div>
+
+<div>
+</div>
+ <div>
+ <h3 class="Head2">Notes</h3>
+ <ol>
+ <li>
+ MPC doesn't directly generate Workbench workspaces, because they depend
+ on an unknown binary file format that it can't generate. Instead of
+ generating files that can be loaded as a Workbench workspace, MPC
+ generates two files representing the workspace:
+ <ol>
+ <li>wb30projects.lst</li>
+ <li>org.eclipse.core.resources.prefs</li>
+ </ol>
+ wb30projects.lst contains comment lines (starting with #) followed by
+ one line per project, listing the full path to the .project file.<br/>
+ org.eclipse.core.resources.prefs also begins with comment lines
+ (starting with #) follwed by the contents of one of the files from
+ Eclipse's workspace format, specifically:
+ <code>.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.core.resources.prefs</code>
+ Unfortunately, this file alone is not enough to actually constitute a
+ workspace because Eclipse uses other binary files in this .settings
+ directory.
+ </li>
+
+ <li><a name="fullpath"></a>WB30 uses Eclipse's <em>linked resource</em>
+ feature to work around the usual requirement that
+ all source code reside in Workbench project directories. These
+ act similar to symbolic links. While convenient so that a
+ developer is not required to conform to Workbench's directory
+ layout, it comes at a price: the target of the link must be
+ specified as a full path. The consequence of this restriction is
+ that, once the WB30 projects get generated, the source directory can
+ not move in the filesystem without re-generating the projects.</li>
+
+ <li><a name="remove_projects"></a>MPC's WB30 Project Generator
+ creates directories named <samp>wb_*</samp> for projects.
+ To remove all WB30 projects from a
+ directory hierarchy, on Linux you can use a command such as:
+<pre>
+ $ find . -name 'wb_*' -type d | xargs rm -rf
+</pre>
+ </li>
+
+ </ol>
+ </div>
+
+</div>
+
+
+<hr>
+
+</body> </html>
View
29 docs/html/rpmworkflow.dot
@@ -0,0 +1,29 @@
+digraph rpmpackaging {
+ rankdir=LR;
+
+ subgraph cluster_completeprocess {
+ // rpmbuild output
+ rpmbuild [shape="box"];
+
+ rpmbuild -> SRPM;
+ rpmbuild -> bRPM;
+
+
+ // inputs to rpmbuild
+ specfile -> rpmbuild ;
+ tarball -> rpmbuild ;
+
+ mwc [shape="box" label="mwc.pl"];
+ rpmscript [shape="box" label="*_rpm.sh script"];
+
+ mwc -> specfile;
+ mwc -> rpmscript;
+ rpmscript -> tarball;
+
+ mwcfiles [label=".mwc files"];
+
+ mwcfiles -> mwc;
+
+
+ }
+}
View
BIN  docs/html/rpmworkflow.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Please sign in to comment.
Something went wrong with that request. Please try again.