Initial commit of Sigil contribution. (FELIX-1142)
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@793581 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/sigil/sigil-builder/readme.html b/sigil/sigil-builder/readme.html
new file mode 100644
index 0000000..2427241
--- /dev/null
+++ b/sigil/sigil-builder/readme.html
@@ -0,0 +1,131 @@
+<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>
\ No newline at end of file