docs/html/RpmSpec.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: RpmSpec Type</title>
  11 </head>
  12
  13 <body>
  14 <div>
  15   <h1 class="Head1">RpmSpec Type documentation</h1>
  16
  17   <div>
  18     <h3 class="Head2">Background/Abstract</h3>
  19     <ul>
  20     <li class="body">The <em>RpmSpec Type</em> generates
  21     <em class="Code">.spec</em> files suitable for use by the <em class="Code"><a
  22     href="http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-rpmbuild.html">rpmbuild</a></em>
  23     utility to build and package.  It additionally creates a Bourne
  24     shell script that automates creation of source tarball and proper
  25     dependency-order building/packaging of <em class="Code">.spec</em> files.
  26     </li>
  27
  28     <li class="body">The RpmSpec type refines the existing
  29     <em>aggregated workspace</em> MPC concept, as well as introduces
  30     the ability to have <em class="Code">specific</em> clauses inside
  31     workspace declarations (<em class="Code">.mwc</em> files).  Consequently,
  32     workspace files utilizing these new features are not
  33     backwards-compatible with prior releases of MPC.</li>
  34
  35     <li class="body">Since RPM is primarily Linux-based, RpmSpec only
  36     officially supports use on Linux-based systems.  It <em>may</em>
  37     work on platforms for which an RPM port exists, but such success
  38     would be coincidental and neither intended, tested, nor
  39     guaranteed.</li>
  40     </ul>
  41   </div>
  42
  43   <div>
  44     <h3 class="Head2">Pre-requisites</h3>
  45     <ul>
  46       <li class="body">The following software items are required and
  47     in the execution path (as well as any of their respective dependencies):
  48       <dl>
  49         <dt>RPM</dt>
  50         <dd>Minimum of version 4.7.1 recommended (not tested with
  51     other versions).</dd>
  52        <dt>Development toolchain</dt>
  53         <dd>This can be the standard development toolchain. Packaging
  54     for other architectures is supported if the toolchain in the path
  55     is a cross-compiler for that architecture.</dd>
  56      </dl>
  57    </ul>
  58  </div>
  59
  60   <div>
  61     <h3 class="Head2">Usage</h3>
  62     <p class="Body">
  63     The RpmSpec type refines an existing concept in MPC known as
  64     <em><a
  65     href="MakeProjectCreator.html#AggregatedWorkspace">aggregate
  66     workspaces</a></em> to define package scopes.  When
  67     <em class="Code">mwc.pl</em> is run on a top-level workspace with
  68     <em class="Code">-type rpmspec</em>, each aggregated workspace is presumed
  69     to define the scope of a package that will become an RPM.
  70     Inter-project dependencies that exist between any projects known to
  71     the top-level workspace automatically turn into inter-package
  72     dependencies in RPMs.
  73     </p>
  74    <h4 class="Head5">Generic workflow</h4>
  75     <div align="center">
  76    <img src="images/rpmworkflow.png" alt="rpm workflow"/>
  77       <h6 align="center">Figure: RPM Workflow</h6>
  78     </div>
  79     <p class="Body">
  80     Presuming <em class="Code">.mwc</em> files already exist, and that
  81     inter-project dependencies are complete and well-formed (i.e.,
  82     contain sufficient <em class="Code">after</em> statements to insure proper
  83     build ordering):
  84     </p>
  85    <ol>
  86      <li><p class="Body">Use the command <em class="Code">mwc.pl -type rpmspec <em>top-level-workspace.mwc</em></em> to generate
  87     <em class="Code">.spec</em> files and <em class="Code">*_rpm.sh</em> builder script.</p></li>
  88
  89      <li><p class="Body">Run the <em class="Code"><em>top-level-workspace</em>_rpm.sh</em>
  90     script to build/package.</p></li>
  91   </ol>
  92  </div>
  93
  94  <div>
  95   <h3 class="Head2">Adapting/Writing Projects for Packaging</h3>
  96    <h4 class="Head5"><a name="mwcnotes"></a>Creating Workspaces</h4>
  97    <p class="Body">The RpmSpec type uses <a
  98     href="MakeProjectCreator.html#AggregatedWorkspace">aggregate
  99     workspaces</a> to define the scope of a package.  In other words,
 100    defining a package involves writing a <em class="Code">.mwc</em> file that
 101    includes all the projects that should go into that package.
 102    An additional <em class="Code">.mwc</em> file must be written for each
 103    additional package.  Finally, these <em>package</em> workspaces get
 104    aggregated into a workspace.
 105
 106    <p class="Body">RPM packages require extra information not needed by "normal"
 107    MPC projects or workspaces.  This information is defined in a
 108    <em class="Code">specific</em> clause in the workspace for the
 109    <em class="Code">rpmspec</em> type, e.g.,
 110
 111    <blockquote>
 112 <p class="Code">// top-level workspace</p>
 113 <p class="Code">workspace {</p>
 114 <p class="Code">&nbsp;&nbsp;specific (rpmspec) {</p>
 115 <p class="Code">&nbsp;&nbsp;&nbsp;&nbsp;rpm_version = 1.0</p>
 116 <p class="Code">&nbsp;&nbsp;&nbsp;&nbsp;rpm_release = 1</p>
 117 <p class="Code">&nbsp;&nbsp;}</p>
 118 <p class="Code">&nbsp;&nbsp;package1.mwc</p>
 119 <p class="Code">&nbsp;&nbsp;package2.mwc</p>
 120 <p class="Code">}</p>
 121    </blockquote>
 122    <p class="Body">
 123    Details on the variables allowed in the <em class="Code">specific</em>
 124    clause can be found in the <a href="../templates/rpmspec.txt">
 125    <em class="Code">$MPC_ROOT/docs/templates/rpmspec.txt</em></a> file.
 126    </p>
 127
 128    <p class="Body">If you use workspaces as a part of
 129    building right now, you may wish to write additional
 130    workspace files specifically for packaging via RPM.
 131
 132    <h4 class="Head5"><a name="installready"></a>Making Projects
 133    <em>Install-Ready</em></h4>
 134    <p class="Body">
 135    MPC-assisted packaging requires some attention from the developer
 136    in order to yield its full potential.  What this means is that in
 137    order for a project to avail itself to be packaged, it must take
 138    care to insure that any collateral (such as files) that it needs to
 139    end up in the package get installed via MPC's <em>install</em> feature.
 140    Note that this feature is currently only implemented within the
 141    <em class="Code">gnuace</em> project type.
 142    </p>
 143    <p class="Body">
 144    Typically, this involves inheriting from the <em class="Code">install</em>
 145    base project in order to enable auto-generation of installation
 146    rules in the makefiles.  MPC defaults to making educated guesses as
 147    to what files should be installed (e.g., for an <em class="Code">exe</em>
 148    project, it figures that the executable should be installed), but a
 149    developer can augment or replace MPC's guesses using
 150    <em class="Code">Install*_Files</em> groupings.  See the documentation on
 151    the <em class="Code">gnuace</em> installation feature for details.
 152    </p>
 153   </div>
 154 </div>
 155
 156 <div>
 157    <h3 class="Head2">Notes</h3>
 158   <h4 class="Head5"><a name="rpmnotes"></a>Notes on Generated RPMs</h4>
 159    <ol>
 160      <li><p class="Body">RPMs are relocatable using the <em class="Code">--prefix</em> or
 161    <em class="Code">--relocate</em> options to <em class="Code">rpm</em>.</p></li>
 162      <li><p class="Body">The RpmSpec type has no control over where the RPM system performs
 163      it's "work" (building, staging,
 164    packaging, etc.).  In the
 165    past, this was often <em class="Code">/usr/src/redhat</em>, though your
 166    system may be configured differently.<br/><em class="Code">rpmbuild</em>
 167    holds this directory in its <em>_topdir</em> configuration
 168    variable. To see the value of <em>_topdir</em> on
 169    your system, execute the following command:</p>
 170    <blockquote>
 171 <p class="Code"><b>$ rpmbuild --showrc | grep '_topdir[^}]'</b></p>
 172 <p class="Code">-14: _topdir    %{getenv:HOME}/rpmbuild</p>
 173 </blockquote>
 174    </li>
 175
 176      <li><p class="Body">Binary RPMs land in <em class="Code"><em>_topdir</em>/RPMS</em>.</p></li>
 177      <li><p class="Body">Source RPMs land in <em class="Code"><em>_topdir</em>/SRPMS</em>.</p></li>
 178    </ol>
 179
 180    <h4 class="Head5"><a name="scriptnotes"></a>Notes on Generated Script</h4>
 181    <ol>
 182      <li><p class="Body">The script takes one optional argument
 183      indicating the architecture for which it should create packages.
 184      The script makes no attempt to "find" a toolchain for that
 185      architecture, instead presuming that whatever toolchain is
 186      needed can be found in the PATH or is specified in the
 187      <em class="Code">.spec</em> file.</p></li>
 188
 189      <li><p class="Body">The script performs a build/install activity for each package.
 190    Installation is not into the running system, but rather into a
 191    "fake" area.  Installation is necessary to satisfy inter-package
 192    dependency requirements.</p><p class="Body">The location of the "fake" area
 193    defaults to <em class="Code">/tmp/mpcrpm</em> but can be changed by setting the
 194    <em class="Code">&lt;%rpm_mpc_temp%&gt;</em> in a workspace
 195    <em class="Code">specific</em> clause, typically in the top-level
 196    workspace.<p></li>
 197
 198
 199    </ol>
 200 </div>
 201
 202
 203 </body> </html>