ChangeLogTag: Wed Dec 22 17:28:56 UTC 2010 Adam Mitz <mitza@ociweb.com>

5 files changed, 294 insertions, 11 deletions

diff --git a/docs/html/MakeProjectCreator.css b/docs/html/MakeProjectCreator.css
index 66b10c69..c9a9a84f 100644
--- a/docs/html/MakeProjectCreator.css
+++ b/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;
+}
diff --git a/docs/html/MakeProjectCreator.html b/docs/html/MakeProjectCreator.html
index 0beb292c..fd586e56 100644
--- a/docs/html/MakeProjectCreator.html
+++ b/docs/html/MakeProjectCreator.html
@@ -215,6 +215,29 @@
 
               <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>
 
@@ -280,6 +303,17 @@
 
               <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>
 
@@ -331,7 +365,7 @@
 
               <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">
@@ -341,7 +375,7 @@
 
               <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">
@@ -351,7 +385,8 @@
 
               <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">
@@ -361,6 +396,17 @@
 
               <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>
 
@@ -1410,6 +1456,14 @@
 
               <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>
@@ -1428,13 +1482,16 @@
             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
@@ -1469,6 +1526,20 @@
             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
@@ -2434,7 +2505,7 @@
           </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>
diff --git a/docs/html/RpmSpec.html b/docs/html/RpmSpec.html
new file mode 100644
index 00000000..ac7ff322
--- /dev/null
+++ b/docs/html/RpmSpec.html
@@ -0,0 +1,174 @@
+<!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>
+    <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>
+    
+  </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:
+   <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">Notes</h3>
+   <h4><a name-"mwcnotes"></a>Notes on 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 <a href="../templates/rpmspec.txt">the
+   <samp>$MPC_ROOT/docs/templates/rpmspec.txt</samp> file.</a>
+   
+   <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="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>
+<address></address>
+<!-- hhmts start --> Last modified: Wed Dec 22 09:48:06 CST 2010 <!-- hhmts end -->
+</body> </html>
diff --git a/docs/html/rpmworkflow.dot b/docs/html/rpmworkflow.dot
new file mode 100644
index 00000000..25fc7006
--- /dev/null
+++ b/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;
+
+                
+        }
+}
diff --git a/docs/html/rpmworkflow.png b/docs/html/rpmworkflow.png
new file mode 100644
index 00000000..3a2de95a
--- /dev/null
+++ b/docs/html/rpmworkflow.png