<html>
<head>
<title>Sigil Build Instructions</title>
</head>
<body>

<h1>Build Instructions</h1>

<h2>1. Install Prerequisites</h2>

<p>A full copy of Eclipse SDK is required to build. This must be
installed in a directory called <code>eclipse</code>, and the full path
should not contain any spaces. For example:</p>

<ul>
	<li><code>C:/eclipse-SDK-3.4/eclipse</code> is GOOD</li>
	<li><code>C:/eclipse-SDK-3.4/</code> is BAD</li>
	<li><code>C:/Program Files/Eclipse 3.4/</code> is VERY BAD</li>
</ul>

<p>This directory (<strong>including</strong> the final <code>eclipse</code>)
will be referred to as the SDK directory.</p>

<h2>2. Setup the Target Platform</h2>

<p>The target platform is the collection of binary plugins and
features against which the source projects are built. It is an Eclipse
installation (with a <code>plugins</code> and <code>features</code>
directory), and so can be setup by downloading the correct zip or
tarball from the Eclipse website. Like the SDK directory, the target
platform must be inside a directory called <code>eclipse</code>. In your
IDE, you should point PDE at the target platform by opening Preferences
and navigating to "Plug-in Development" --&gt; "Target Platform". Click
Browse and select the <code>eclipse</code> directory.</p>

<p>Note that since we are building SDK plugins, the Target Platform
will be a full SDK (eg "Eclipse Classic SDK"). Therefore we can reuse
the same SDK directory that we setup in the previous step. However it
can also be useful to separate these because we might want to use
different Eclipse versions for each function. For example, we may want
to use Eclipse 3.4 to build a 3.3-based product.</p>

<h2>3. Create and edit <code>user.properties</code></h2>

<p>User-specific properties are supplied in the file <code>user.properties</code>.
After checkout this file does not exist, so please copy <code>template.user.properties</code>
to <code>user.properties</code> and change the following settings:</p>

<ul>
	<li><code>target.platform</code>: this should be set to the <strong>parent
	</strong> directory of the <code>eclipse</code> directory which contains the
	Target Platform.</li>
	<li><code>eclipse.install.dir</code>: the SDK directory (including
	final <code>eclipse</code> segment).</li>
</ul>

<p>Do not check <code>user.properties</code> into version control:
the settings inside are specific to your machine.</p>

<h2>4. Configure the Update Site URL</h2>

<p>The Update Site URL can be specified by setting the <code>updateUrl</code>
property in <code>project.properties</code> . This will be copied into
the <code>feature.xml</code> descriptor for each feature that is part of
the build. For this to work, the update site URL setting in the <code>feature.xml</code>
of each source feature project must be set to the following placeholder
string: <code>http://replace.with.real.url</code></p>

<h2>5. Execute the Build</h2>

<p>Execute a full build by running the <code>pdebuild</code> target
in ANT, e.g.:</p>

<pre>
    ant pdebuild
</pre>

<p>This will generate a directory named <code>target/tmp/eclipse</code>
which contains a <code>plugins</code> directory for the built plugin
JARs and a <code>features</code> directory for the built features. If
the build fails then compilation logs for each plugin can be found in <code>target/N.Sigil/compilelogs/plugins</code>.</p>

<h2>6. Deploy to Update Site</h2>

<p>After the features and plugins are built we can deploy them to an
update site on the local filesystem. The update site directory must
already exist with the following layout:</p>

<pre>
${updateSiteDir}/
 |--plugins/
 |--features/
 \--site.xml
</pre>

<p>And <code>site.xml</code> must have at least the following
content:</p>

<pre>
&lt;site&gt;
    &lt;category-def name="Sigil" label="Sigil"&gt;
        &lt;description&gt;Blah blah&lt;/description&gt;
    &lt;/category-def&gt;
&lt;/site&gt;
</pre>

<p>It can also have any number of pre-existing <code>&lt;feature&gt;</code>
entries as direct children of the <code>&lt;site&gt;</code> element.</p>

<p>Next set the <code>updateSiteDir</code> property in <code>project.properties</code>
to point at the above directory. Now we can run the deploy target as
follows:</p>

<pre>
    ant copy.updateSite
</pre>

<p>This will copy all of the plugin and feature JARs that were built
in the previous step into the update site directory. It will also add a
new entry into <code>site.xml</code> for each feature. Note that the
update site directory will grow continually. Since the plugins and
features are generated with a timestamp in their version qualifier (e.g.
1.2.3.200808091200 for version 1.2.3 built on 9 Aug 2008 at 12 o'clock
GMT), Eclipse Update Manager will always select the newest version
available.</p>

<p>NB: the deploy target will overwrite <code>site.xml</code>. A
backup will be saved in <code>site.xml.bak</code> but this backup will
be overwritten next time the build is run.</p>
</body>
</html>