| Richard S. Hall | 85bafab | 2009-07-13 13:25:46 +0000 | [diff] [blame] | 1 | <html> |
| 2 | <head> |
| 3 | <title>Sigil Build Instructions</title> |
| 4 | </head> |
| 5 | <body> |
| 6 | |
| 7 | <h1>Build Instructions</h1> |
| 8 | |
| 9 | <h2>1. Install Prerequisites</h2> |
| 10 | |
| 11 | <p>A full copy of Eclipse SDK is required to build. This must be |
| 12 | installed in a directory called <code>eclipse</code>, and the full path |
| 13 | should not contain any spaces. For example:</p> |
| 14 | |
| 15 | <ul> |
| 16 | <li><code>C:/eclipse-SDK-3.4/eclipse</code> is GOOD</li> |
| 17 | <li><code>C:/eclipse-SDK-3.4/</code> is BAD</li> |
| 18 | <li><code>C:/Program Files/Eclipse 3.4/</code> is VERY BAD</li> |
| 19 | </ul> |
| 20 | |
| 21 | <p>This directory (<strong>including</strong> the final <code>eclipse</code>) |
| 22 | will be referred to as the SDK directory.</p> |
| 23 | |
| 24 | <h2>2. Setup the Target Platform</h2> |
| 25 | |
| 26 | <p>The target platform is the collection of binary plugins and |
| 27 | features against which the source projects are built. It is an Eclipse |
| 28 | installation (with a <code>plugins</code> and <code>features</code> |
| 29 | directory), and so can be setup by downloading the correct zip or |
| 30 | tarball from the Eclipse website. Like the SDK directory, the target |
| 31 | platform must be inside a directory called <code>eclipse</code>. In your |
| 32 | IDE, you should point PDE at the target platform by opening Preferences |
| 33 | and navigating to "Plug-in Development" --> "Target Platform". Click |
| 34 | Browse and select the <code>eclipse</code> directory.</p> |
| 35 | |
| 36 | <p>Note that since we are building SDK plugins, the Target Platform |
| 37 | will be a full SDK (eg "Eclipse Classic SDK"). Therefore we can reuse |
| 38 | the same SDK directory that we setup in the previous step. However it |
| 39 | can also be useful to separate these because we might want to use |
| 40 | different Eclipse versions for each function. For example, we may want |
| 41 | to use Eclipse 3.4 to build a 3.3-based product.</p> |
| 42 | |
| 43 | <h2>3. Create and edit <code>user.properties</code></h2> |
| 44 | |
| 45 | <p>User-specific properties are supplied in the file <code>user.properties</code>. |
| 46 | After checkout this file does not exist, so please copy <code>template.user.properties</code> |
| 47 | to <code>user.properties</code> and change the following settings:</p> |
| 48 | |
| 49 | <ul> |
| 50 | <li><code>target.platform</code>: this should be set to the <strong>parent |
| 51 | </strong> directory of the <code>eclipse</code> directory which contains the |
| 52 | Target Platform.</li> |
| 53 | <li><code>eclipse.install.dir</code>: the SDK directory (including |
| 54 | final <code>eclipse</code> segment).</li> |
| 55 | </ul> |
| 56 | |
| 57 | <p>Do not check <code>user.properties</code> into version control: |
| 58 | the settings inside are specific to your machine.</p> |
| 59 | |
| 60 | <h2>4. Configure the Update Site URL</h2> |
| 61 | |
| 62 | <p>The Update Site URL can be specified by setting the <code>updateUrl</code> |
| 63 | property in <code>project.properties</code> . This will be copied into |
| 64 | the <code>feature.xml</code> descriptor for each feature that is part of |
| 65 | the build. For this to work, the update site URL setting in the <code>feature.xml</code> |
| 66 | of each source feature project must be set to the following placeholder |
| 67 | string: <code>http://replace.with.real.url</code></p> |
| 68 | |
| 69 | <h2>5. Execute the Build</h2> |
| 70 | |
| 71 | <p>Execute a full build by running the <code>pdebuild</code> target |
| 72 | in ANT, e.g.:</p> |
| 73 | |
| 74 | <pre> |
| 75 | ant pdebuild |
| 76 | </pre> |
| 77 | |
| 78 | <p>This will generate a directory named <code>target/tmp/eclipse</code> |
| 79 | which contains a <code>plugins</code> directory for the built plugin |
| 80 | JARs and a <code>features</code> directory for the built features. If |
| 81 | the build fails then compilation logs for each plugin can be found in <code>target/N.Sigil/compilelogs/plugins</code>.</p> |
| 82 | |
| 83 | <h2>6. Deploy to Update Site</h2> |
| 84 | |
| 85 | <p>After the features and plugins are built we can deploy them to an |
| 86 | update site on the local filesystem. The update site directory must |
| 87 | already exist with the following layout:</p> |
| 88 | |
| 89 | <pre> |
| 90 | ${updateSiteDir}/ |
| 91 | |--plugins/ |
| 92 | |--features/ |
| 93 | \--site.xml |
| 94 | </pre> |
| 95 | |
| 96 | <p>And <code>site.xml</code> must have at least the following |
| 97 | content:</p> |
| 98 | |
| 99 | <pre> |
| 100 | <site> |
| 101 | <category-def name="Sigil" label="Sigil"> |
| 102 | <description>Blah blah</description> |
| 103 | </category-def> |
| 104 | </site> |
| 105 | </pre> |
| 106 | |
| 107 | <p>It can also have any number of pre-existing <code><feature></code> |
| 108 | entries as direct children of the <code><site></code> element.</p> |
| 109 | |
| 110 | <p>Next set the <code>updateSiteDir</code> property in <code>project.properties</code> |
| 111 | to point at the above directory. Now we can run the deploy target as |
| 112 | follows:</p> |
| 113 | |
| 114 | <pre> |
| 115 | ant copy.updateSite |
| 116 | </pre> |
| 117 | |
| 118 | <p>This will copy all of the plugin and feature JARs that were built |
| 119 | in the previous step into the update site directory. It will also add a |
| 120 | new entry into <code>site.xml</code> for each feature. Note that the |
| 121 | update site directory will grow continually. Since the plugins and |
| 122 | features are generated with a timestamp in their version qualifier (e.g. |
| 123 | 1.2.3.200808091200 for version 1.2.3 built on 9 Aug 2008 at 12 o'clock |
| 124 | GMT), Eclipse Update Manager will always select the newest version |
| 125 | available.</p> |
| 126 | |
| 127 | <p>NB: the deploy target will overwrite <code>site.xml</code>. A |
| 128 | backup will be saved in <code>site.xml.bak</code> but this backup will |
| 129 | be overwritten next time the build is run.</p> |
| 130 | </body> |
| 131 | </html> |