+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id268444"></a>4. Rebuilding and customizing MyPLC</h2></div></div></div>
+<p>The MyPLC package, though distributed as an RPM, is not a
+ traditional package that can be easily rebuilt from SRPM. The
+ requisite build environment is quite extensive and numerous
+ assumptions are made throughout the PlanetLab source code base,
+ that the build environment is based on Fedora Core 4 and that
+ access to a complete Fedora Core 4 mirror is available.</p>
+<p>For this reason, it is recommended that you only rebuild
+ MyPLC (or any of its components) from within the MyPLC development
+ environment. The MyPLC development environment is similar to MyPLC
+ itself in that it is a portable filesystem contained within a
+ <span><strong class="command">chroot</strong></span> jail. The filesystem contains all the
+ necessary tools required to rebuild MyPLC, as well as a snapshot
+ of the PlanetLab source code base in the form of a local CVS
+ repository.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id268469"></a>4.1. Installation</h3></div></div></div>
+<p>Install the MyPLC development environment similarly to how
+ you would install MyPLC. You may install both packages on the same
+ host system if you wish. As with MyPLC, the MyPLC development
+ environment should be treated as a monolithic software
+ application, and any files present in the
+ <span><strong class="command">chroot</strong></span> jail should not be modified directly, as
+ they are subject to upgrade.</p>
+<div class="example">
+<a name="id268487"></a><p class="title"><b>Example 7. Installing the MyPLC development environment.</b></p>
+<pre class="programlisting"># If your distribution supports RPM
+rpm -U http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
+
+# If your distribution does not support RPM
+cd /tmp
+wget http://build.planet-lab.org/build/myplc-0_4-rc2/RPMS/i386/myplc-devel-0.4-2.planetlab.i386.rpm
+cd /
+rpm2cpio /tmp/myplc-devel-0.4-2.planetlab.i386.rpm | cpio -diu</pre>
+</div>
+<p>The MyPLC development environment installs the following
+ files and directories:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="filename">/plc/devel/root.img</code>: The
+ main root filesystem of the MyPLC development environment. This
+ file is an uncompressed ext3 filesystem that is loopback mounted
+ on <code class="filename">/plc/devel/root</code> when the MyPLC
+ development environment is initialized. This filesystem, even
+ when mounted, should be treated as an opaque binary that can and
+ will be replaced in its entirety by any upgrade of the MyPLC
+ development environment.</p></li>
+<li><p><code class="filename">/plc/devel/root</code>: The mount
+ point for
+ <code class="filename">/plc/devel/root.img</code>.</p></li>
+<li>
+<p><code class="filename">/plc/devel/data</code>: The directory
+ where user data and generated files are stored. This directory
+ is bind mounted onto <code class="filename">/plc/devel/root/data</code>
+ so that it is accessible as <code class="filename">/data</code> from
+ within the <span><strong class="command">chroot</strong></span> jail. Files in this
+ directory are marked with
+ <span><strong class="command">%config(noreplace)</strong></span> in the RPM. Symlinks
+ ensure that the following directories (relative to
+ <code class="filename">/plc/devel/root</code>) are stored outside the
+ root filesystem image:</p>
+<div class="itemizedlist"><ul type="circle">
+<li><p><code class="filename">/etc/planetlab</code>: This
+ directory contains the configuration files that define your
+ MyPLC development environment.</p></li>
+<li><p><code class="filename">/cvs</code>: A
+ snapshot of the PlanetLab source code is stored as a CVS
+ repository in this directory. Files in this directory will
+ <span class="bold"><strong>not</strong></span> be updated by an upgrade of
+ <code class="filename">myplc-devel</code>. See <a href="#UpdatingCVS" title="4.4. Updating CVS">Section 4.4, “Updating CVS”</a> for more information about updating
+ PlanetLab source code.</p></li>
+<li><p><code class="filename">/build</code>:
+ Builds are stored in this directory. This directory is bind
+ mounted onto <code class="filename">/plc/devel/root/build</code> so that
+ it is accessible as <code class="filename">/build</code> from within the
+ <span><strong class="command">chroot</strong></span> jail. The build scripts in this
+ directory are themselves source controlled; see <a href="#BuildingMyPLC" title="4.3. Building MyPLC">Section 4.3, “Building MyPLC”</a> for more information about executing
+ builds.</p></li>
+</ul></div>
+</li>
+<li><p><code class="filename">/etc/init.d/plc-devel</code>: This file is
+ a System V init script installed on your host filesystem, that
+ allows you to start up and shut down the MyPLC development
+ environment with a single command.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id268676"></a>4.2. Fedora Core 4 mirror requirement</h3></div></div></div>
+<p>The MyPLC development environment requires access to a
+ complete Fedora Core 4 i386 RPM repository, because several
+ different filesystems based upon Fedora Core 4 are constructed
+ during the process of building MyPLC. You may configure the
+ location of this repository via the
+ <code class="envar">PLC_DEVEL_FEDORA_URL</code> variable in
+ <code class="filename">/plc/devel/data/etc/planetlab/plc_config.xml</code>. The
+ value of the variable should be a URL that points to the top
+ level of a Fedora mirror that provides the
+ <code class="filename">base</code>, <code class="filename">updates</code>, and
+ <code class="filename">extras</code> repositories, e.g.,</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="filename">file:///data/fedora</code></p></li>
+<li><p><code class="filename">http://coblitz.planet-lab.org/pub/fedora</code></p></li>
+<li><p><code class="filename">ftp://mirror.cs.princeton.edu/pub/mirrors/fedora</code></p></li>
+<li><p><code class="filename">ftp://mirror.stanford.edu/pub/mirrors/fedora</code></p></li>
+<li><p><code class="filename">http://rpmfind.net/linux/fedora</code></p></li>
+</ul></div>
+<p>As implied by the list, the repository may be located on
+ the local filesystem, or it may be located on a remote FTP or
+ HTTP server. URLs beginning with <code class="filename">file://</code>
+ should exist at the specified location relative to the root of
+ the <span><strong class="command">chroot</strong></span> jail. For optimum performance and
+ reproducibility, specify
+ <code class="envar">PLC_DEVEL_FEDORA_URL=file:///data/fedora</code> and
+ download all Fedora Core 4 RPMS into
+ <code class="filename">/plc/devel/data/fedora</code> on the host system
+ after installing <code class="filename">myplc-devel</code>. Use a tool
+ such as <span><strong class="command">wget</strong></span> or <span><strong class="command">rsync</strong></span> to
+ download the RPMS from a public mirror:</p>
+<div class="example">
+<a name="id268807"></a><p class="title"><b>Example 8. Setting up a local Fedora Core 4 repository.</b></p>
+<pre class="programlisting">mkdir -p /plc/devel/data/fedora
+cd /plc/devel/data/fedora
+
+for repo in core/4/i386/os core/updates/4/i386 extras/4/i386 ; do
+ wget -m -nH --cut-dirs=3 http://coblitz.planet-lab.org/pub/fedora/linux/$repo
+done</pre>
+</div>
+<p>Change the repository URI and <span><strong class="command">--cut-dirs</strong></span>
+ level as needed to produce a hierarchy that resembles:</p>
+<pre class="programlisting">/plc/devel/data/fedora/core/4/i386/os
+/plc/devel/data/fedora/core/updates/4/i386
+/plc/devel/data/fedora/extras/4/i386</pre>
+<p>A list of additional Fedora Core 4 mirrors is available at
+ <a href="http://fedora.redhat.com/Download/mirrors.html" target="_top">http://fedora.redhat.com/Download/mirrors.html</a>.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="BuildingMyPLC"></a>4.3. Building MyPLC</h3></div></div></div>
+<p>All PlanetLab source code modules are built and installed
+ as RPMS. A set of build scripts, checked into the
+ <code class="filename">build/</code> directory of the PlanetLab CVS
+ repository, eases the task of rebuilding PlanetLab source
+ code.</p>
+<p>To build MyPLC, or any PlanetLab source code module, from
+ within the MyPLC development environment, execute the following
+ commands as root:</p>
+<div class="example">
+<a name="id268873"></a><p class="title"><b>Example 9. Building MyPLC.</b></p>
+<pre class="programlisting"># Initialize MyPLC development environment
+service plc-devel start
+
+# Enter development environment
+chroot /plc/devel/root su -
+
+# Check out build scripts into a directory named after the current
+# date. This is simply a convention, it need not be followed
+# exactly. See build/build.sh for an example of a build script that
+# names build directories after CVS tags.
+DATE=$(date +%Y.%m.%d)
+cd /build
+cvs -d /cvs checkout -d $DATE build
+
+# Build everything
+make -C $DATE</pre>
+</div>
+<p>If the build succeeds, a set of binary RPMS will be
+ installed under
+ <code class="filename">/plc/devel/data/build/$DATE/RPMS/</code> that you
+ may copy to the
+ <code class="filename">/var/www/html/install-rpms/planetlab</code>
+ directory of your MyPLC installation (see <a href="#Installation" title="2. Installation">Section 2, “Installation”</a>).</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="UpdatingCVS"></a>4.4. Updating CVS</h3></div></div></div>
+<p>A complete snapshot of the PlanetLab source code is included
+ with the MyPLC development environment as a CVS repository in
+ <code class="filename">/plc/devel/data/cvs</code>. This CVS repository may
+ be accessed like any other CVS repository. It may be accessed
+ using an interface such as <a href="http://www.freebsd.org/projects/cvsweb.html" target="_top">CVSweb</a>,
+ and file permissions may be altered to allow for fine-grained
+ access control. Although the files are included with the
+ <code class="filename">myplc-devel</code> RPM, they are <span class="bold"><strong>not</strong></span> subject to upgrade once installed. New
+ versions of the <code class="filename">myplc-devel</code> RPM will install
+ updated snapshot repositories in
+ <code class="filename">/plc/devel/data/cvs-%{version}-%{release}</code>,
+ where <code class="literal">%{version}-%{release}</code> is replaced with
+ the version number of the RPM.</p>
+<p>Because the CVS repository is not automatically upgraded,
+ if you wish to keep your local repository synchronized with the
+ public PlanetLab repository, it is highly recommended that you
+ use CVS's support for <a href="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Tracking_third-party_sources" target="_top">vendor
+ branches</a> to track changes. Vendor branches ease the task
+ of merging upstream changes with your local modifications. To
+ import a new snapshot into your local repository (for example,
+ if you have just upgraded from
+ <code class="filename">myplc-devel-0.4-2</code> to
+ <code class="filename">myplc-devel-0.4-3</code> and you notice the new
+ repository in <code class="filename">/plc/devel/data/cvs-0.4-3</code>),
+ execute the following commands as root from within the MyPLC
+ development environment:</p>
+<div class="example">
+<a name="id269004"></a><p class="title"><b>Example 10. Updating /data/cvs from /data/cvs-0.4-3.</b></p>
+<p><span class="bold"><strong>Warning</strong></span>: This may cause
+ severe, irreversible changes to be made to your local
+ repository. Always tag your local repository before
+ importing.</p>
+<pre class="programlisting"># Initialize MyPLC development environment
+service plc-devel start
+
+# Enter development environment
+chroot /plc/devel/root su -
+
+# Tag current state
+cvs -d /cvs rtag before-myplc-0_4-3-merge
+
+# Export snapshot
+TMP=$(mktemp -d /data/export.XXXXXX)
+pushd $TMP
+cvs -d /data/cvs-0.4-3 export -r HEAD .
+cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
+popd
+rm -rf $TMP</pre>
+</div>
+<p>If there any merge conflicts, use the command suggested by
+ CVS to help the merge. Explaining how to fix merge conflicts is
+ beyond the scope of this document; consult the CVS documentation
+ for more information on how to use CVS.</p>
+</div>
+</div>