| <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" --> "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> |
| <site> |
| <category-def name="Sigil" label="Sigil"> |
| <description>Blah blah</description> |
| </category-def> |
| </site> |
| </pre> |
| |
| <p>It can also have any number of pre-existing <code><feature></code> |
| entries as direct children of the <code><site></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> |