Difference between revisions of "Building an Update Site using Buckminster"

From Eclipsepedia

Jump to: navigation, search
(New page: ==Creating the Update Site Project== #Right click in the Package Explorer and select ''New'' -> ''Project'' #In the ''New Project'' wizard that pops up, open the ''Plug-in Development'' fo...)
 
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
This is a step by step instruction on how to create an update site using Buckminster. It assumes that you already have some features that you want to include on the site and that you have the Buckminster core and pde support installed in the IDE.
 +
 +
=P2 repositories using the 3.5 release and beyond=
 +
Buckminster recognizes a normal Eclipse Feature as a valid description of a P2 enabled site. Actions has been added to the feature so that a P2 site can be built automatically. The build can include steps to normalize, sign, and pack the site.
 +
 +
The process is very simple.
 +
#Create a feature project
 +
#Add all features that you want published to the site
 +
#Add categorization to the build.properties
 +
#Build the site
 +
 +
===The feature.xml file===
 +
The content of the feature.xml file is used like this:
 +
{| {{Greytable}}
 +
|-
 +
!feature.xml
 +
!generated repository
 +
|- valign="top"
 +
|Label
 +
|Name of the metadata repository
 +
|- valign="top"
 +
|Included features
 +
|Root IU's
 +
|- valign="top"
 +
|Discovery sites
 +
|Site references
 +
|- valign="top"
 +
|Mirrors Site
 +
|Mirrors Site
 +
|}
 +
 +
Please note that since this feature is a description of the site as a whole, it is not included in the generated site.
 +
 +
===The build.properties file===
 +
Some additional information (such as categories) can be provided in the build.properties file. An editor pane
 +
for this file is already readily available in the standard PDE feature editor.
 +
 +
====Category declaration====
 +
A category is declared like this:
 +
category.id.<category id>=<category label>
 +
 +
Example:
 +
category.id.core=Buckminster (core)
 +
 +
====Category membership====
 +
Category membership is declared as:
 +
category.members.<category id>=<feature id>[,<feature id>]*
 +
 +
Example:
 +
category.members.core=org.eclipse.buckminster.core.feature
 +
category.members.optional=org.eclipse.buckminster.cvs.feature,org.eclipse.buckminster.svn.feature,...
 +
 +
====Category description====
 +
It is also possible to add a category description as:
 +
category.description.<category id>=<A verbose description of the category>
 +
 +
Example:
 +
category.description.buckminster=This is the category that contains Buckminster core functionality
 +
 +
====The default category====
 +
A default category can be used for capturing all included features not
 +
covered by membership:
 +
category.default=<category id>
 +
 +
====Translations====
 +
All category fields are subject to translation via the feature.properties file. Example:
 +
category.description.buckminster=%CoreCategoryDesc
 +
 +
In feature.properties:
 +
CoreCategoryDesc=This is the category that contains Buckminster core functionality
 +
 +
===The properties provided when building===
 +
Properties that controls the build can be provided in three different ways:
 +
#As a separate properties file referenced when you execute the build
 +
#As system properties, i.e. -Dxxx=yyy on the command line
 +
#As preferences in your workspace using ''Windows'' -> ''Preferences'' -> ''Run/Debug'' -> ''String substitution''
 +
 +
The properties that are relevant for the site generation are:
 +
{| {{Greytable}}
 +
|-
 +
!Name
 +
!Value
 +
!Example
 +
|- valign="top"
 +
|buckminster.output.root
 +
|Absolute path in the local filesystem that controls the output of the build
 +
|/home/bertil/build.output
 +
|- valign="top"
 +
|buckminster.temp.root
 +
|Absolute path in the local filesystem that controls where temporary content ends up during the build
 +
|/home/bertil/tmp/build.tmp
 +
|- valign="top"
 +
|eclipse.committer.name
 +
|'''Only applicable to Eclipse signing''' Committer name used when doing signing at Eclipse.org. This committer must have signing priviligies
 +
|bertil
 +
|- valign="top"
 +
|eclipse.committer.password
 +
|'''Only applicable to Eclipse signing''' Password for the eclipse committer
 +
|blue$25x
 +
|- valign="top"
 +
|local.keystore.path
 +
|'''Only applicable to local signing''' Absolute path in the local filesystem that appoints your personal certificate
 +
|/home/bertil/certificates/personal.certificate
 +
|- valign="top"
 +
|local.keystore.alias
 +
|Alias used by the local keystore
 +
|thomas
 +
|- valign="top"
 +
|local.keystore.password
 +
|Password for the local keystore
 +
|kitty123
 +
|- valign="top"
 +
|site.pack200
 +
|A boolean value controlling pack200 (and normalization if signing is enabled
 +
|true or false
 +
|- valign="top"
 +
|site.signing
 +
|A boolean value controlling signing
 +
|true or false
 +
|- valign="top"
 +
|signing.type
 +
|The type of signing to use. Can be either eclipse.remote (requires Eclipse committer credentials) or local (requires local certificate)
 +
|eclipse.remote
 +
|}
 +
 +
===The eclipse.remote signing===
 +
This is a special type of signing added to support builds intended to be released at the eclipse.org download site. The signing requires that the one who runs the action can provide credentials for an eclipse committer that has signing privileges.
 +
 +
If enabled, the build will package all relevant jars in a zip file and send it over to Eclipse.org using scp. It will request them to be signed by adding them to the queue for the Eclipse signer and then await the result. Once the signing is complete, it will be picked up and the build will continue. Although sometimes a bit slow (more then 20 minutes is rare), the process is fully automatic and does not require any manual intervention.
 +
 +
===Using local signing===
 +
Local signing can be used by anyone interested in signing the jars that are included in the generated site. To use this, you must create a personal certificate. This is done with the <tt>keytool</tt> executable. You will find it in the <tt>bin</tt> catalog of your JDK.
 +
 +
Type in:<pre>
 +
keytool -genkeypair -keystore <path to keystore file> -alias <your alias>
 +
</pre>
 +
<table class="grey">
 +
<caption>Suggestions:</caption>
 +
<tr>
 +
<td>&lt;path to keystore file&gt;</td>
 +
<td>/home/bertil/certificates/personal.certificate</td>
 +
</tr>
 +
<tr>
 +
<td>&lt;your alias&gt;</td>
 +
<td>A short name like 'bertil', 'betty', etc.</td>
 +
</tr>
 +
</table>
 +
 +
You will be asked for some information about name, location, and password. Enter some sane values. Finally you will be asked to confirm the information and you are then asked if you want the same password as for the keystore - simply hit return, you do not want an additional password.
 +
 +
==Building the site==
 +
Right-click on your project, select ''Buckminster'' -> ''Invoke action'' -> ''site.p2''
 +
 +
==Headless builds==
 +
The site can also be built from the command line using a headless setup. Simply issue the command:
 +
<pre>
 +
buckminster -d <your workspace> perform org.test.update#site.p2
 +
</pre>
 +
 +
==Tips==
 +
If you encounter problems to build your update site, please check file META-INF/MANIFEST.MF of all your plugins included in your features.
 +
 +
The MANIFEST.MF shall contains following line:
 +
  Bundle-ManifestVersion: 2
 +
 +
If not, add it to your file. Then apply all proposed quick fixes to have a full compliant manifest, at the end there should be no warnings (at least for MANIFEST.MF).
 +
 +
=Legacy Update sites=
 
==Creating the Update Site Project==
 
==Creating the Update Site Project==
 +
To Buckminster, an update site is not different from any other type of component. We need to keep the definition of the update site in a project, and we need some additional meta data to enable convenient building of the site. The first step is to create the update site project:
 
#Right click in the Package Explorer and select ''New'' -> ''Project''
 
#Right click in the Package Explorer and select ''New'' -> ''Project''
 
#In the ''New Project'' wizard that pops up, open the ''Plug-in Development'' folder
 
#In the ''New Project'' wizard that pops up, open the ''Plug-in Development'' folder
 
#Click on ''Update Site Project''
 
#Click on ''Update Site Project''
#Give the project a name. We use '''org.test.update'''
+
#Give the project a name. In this example we use '''org.test.update'''
 
#Click on ''Finish''
 
#Click on ''Finish''
  
 
The project appears in the workspace and it contains one single file, an empty '''site.xml'''. Buckminster will use this as the update site template. This means that you can add site categories to this file but you should ''not'' add any features. Buckminster will generate a new site.xml where the features are added.
 
The project appears in the workspace and it contains one single file, an empty '''site.xml'''. Buckminster will use this as the update site template. This means that you can add site categories to this file but you should ''not'' add any features. Buckminster will generate a new site.xml where the features are added.
  
==Creating an index.html file==
+
===Creating an index.html file===
Just create an empty file for now and call it '''index.html'''. You can add content to this file that will be what the user will see if they happen to access your update site with a browser.
+
Just create an empty file in the root folder of your new update site project for now and call it '''index.html'''. You can add content to this file that will be what the user will see if they happen to access your update site with a browser.
 
+
==Creating the Component Specification==
+
Now we need to add some content to our site. This is done by adding a Buckminster CSPEC to the project.
+
  
#Right click on the project and select ''New'' -> ''Other''
+
===Creating the Component Specification===
 +
Buckminster describes all components in terms of CSPECs. The update site is no exception. Here are the steps to create such a CSPEC and enter the needed information:
 +
#Right click on the update site project and select ''New'' -> ''Other''
 
#In the ''New'' wizard that pops up, open the ''Buckminster'' folder
 
#In the ''New'' wizard that pops up, open the ''Buckminster'' folder
 
#Select ''Component Specification file'' and click on ''Next''
 
#Select ''Component Specification file'' and click on ''Next''
 
#Click on ''Finish'' to accept the default values for ''Container:'' and ''File name:''
 
#Click on ''Finish'' to accept the default values for ''Container:'' and ''File name:''
  
A file named '''buckminster.cspec''' is created in the project and the Buckminster CSPEC editor opens:
+
A file named '''buckminster.cspec''' is created in the project and the Buckminster CSPEC editor opens. Do not change the name of this file.
  
===Main information===
+
====Main information====
 
*The name of the component is normally the same as the name of the project. This makes it easier to find the component.
 
*The name of the component is normally the same as the name of the project. This makes it easier to find the component.
 
*The component type must in our case be set to '''buckminster'''.
 
*The component type must in our case be set to '''buckminster'''.
 
*The version can be any OSGi compliant version such as '''1.0.0'''
 
*The version can be any OSGi compliant version such as '''1.0.0'''
  
===Artifacts===
+
====Artifacts====
 
Artifacts denotes files and folders that are present inside of a component. The action that will create the update site needs to know about the '''site.xml''' template and other files to copy so we need to add that to our specification:
 
Artifacts denotes files and folders that are present inside of a component. The action that will create the update site needs to know about the '''site.xml''' template and other files to copy so we need to add that to our specification:
 
#Click on the Artifacts tab
 
#Click on the Artifacts tab
 
#Click on ''New'' below the Artifacts table
 
#Click on ''New'' below the Artifacts table
#Enter the name '''site.template'''
+
#Enter a name such as '''site.template'''
 
#Click on the ''New'' button next to the ''Path'' table
 
#Click on the ''New'' button next to the ''Path'' table
 
#Enter the name '''site.xml''' in the dialog that pops up and click ''OK''
 
#Enter the name '''site.xml''' in the dialog that pops up and click ''OK''
Line 40: Line 208:
 
We now have two artifacts, each with one path. The separation is necessary in this particular case since the build action will reference the artifacs separately. An artifact may have several paths and you can add as many files and folders as you wish to the ''site.rootFiles'' artifact.
 
We now have two artifacts, each with one path. The separation is necessary in this particular case since the build action will reference the artifacs separately. An artifact may have several paths and you can add as many files and folders as you wish to the ''site.rootFiles'' artifact.
  
===Dependencies===
+
====Dependencies====
 
We need to define the features that will be included on the update site. Buckminster considers them to be ''dependencies'':
 
We need to define the features that will be included on the update site. Buckminster considers them to be ''dependencies'':
 
#Click on the ''Dependencies'' tab
 
#Click on the ''Dependencies'' tab
Line 49: Line 217:
 
##Click ''OK''
 
##Click ''OK''
  
===Groups (categories)===
+
====Groups====
This step is optional unless you want to categorize the contents of the update site. The build action will automatically match groups that it finds in the CSPEC with categories that it finds in the site template. Let's assume that we added the two categories '''Basic''' and '''Optional''' to the '''site.xml''' file when we edited it earlier. Now we want to divide our features into these two categories:
+
The build action will expect one prerequisite that lists all the feature jars and one that lists all plugin jars. Luckily for us, Buckminster has already generated CSPEC's for all features with attributes that will provide just that. A feature will always have the two public attributes:
#Click on the ''Groups'' tab
+
* '''feature.jars'''
#For each category, repeat the following:
+
:This is the transitive closure of all features (including the feature itself) in jared format.
##Click on ''New'' just below the Groups table
+
* '''bundle.jars'''
##Enter the name of the group. In our example '''Basic''' or '''Optional'''
+
:This is all the plugins that the transitive closure of all features is referencing in jared format.
##For each feature that should be included in this group
+
###Click on ''New'' just next to the prerequisites table
+
###Select a feature from the drop down menu.
+
###Enter the name '''feature.jars'''
+
###Click OK
+
  
===The feature.jars group===
+
Since we don't have a feature that describes the update site itself, we need to create two new groups. One that group all the feature.jars together, and one that group all the bundle.jars together.
We need one group that contains all features that should be present on the update site. If we
+
were using categories in the previous step, this group will simply contain them. If we don't have categories, this group will reference the features directly. In the latter case, the group is created in exactly the same way as described for the category groups. In the former case, we do like this:
+
#Click on the ''Groups'' tab
+
 
#Click on ''New'' just below the Groups table
 
#Click on ''New'' just below the Groups table
 
#Enter the name of the group. We call it '''feature.jars'''
 
#Enter the name of the group. We call it '''feature.jars'''
#For each category that should be included in this group
+
#For each feature that should be included in this group
 
##Click on ''New'' just next to the prerequisites table
 
##Click on ''New'' just next to the prerequisites table
##Leave the component name blank
+
##Select a feature from the drop down menu.
##Select the category group using the drop down menu.
+
##Enter the name <font color=blue>'''feature.jars'''</font>
 
##Click OK
 
##Click OK
  
===The bundle.jars group===
+
Repeat these steps for a group that is called '''bundle.jars''' that references the <font color=blue>'''bundle.jars'''</font> attribute of each feature.
In addition to finding all features to include, the action also needs to know about all bundles that those features are referencing. Each feature exposes this with a special attribute '''bundle.jars''' so the only thing we need to do is to group them together:
+
  
 +
=====Defining Site Categories=====
 +
This step is optional unless you want to categorize the contents of the update site. In order to define a Site Category, you must first create the category in the '''site.xml''' file and then add it as a group in the CSPEC.
 +
 +
In order to create a category in the '''site.xml''' file, do the following:
 +
#Double click on the '''site.xml''' file. The Update Site Editor opens
 +
#On the ''Site Map'' tab, click ''New Category''
 +
#Give the category a name. In this example we will use '''Basic'''
 +
#Add a label such as '''Basic features'''
 +
 +
Repeat these steps and create an additional categogy named '''Optional''' with label '''Optional features'''
 +
 +
Back to the CSPEC editor:
 +
#Click on the ''Groups'' tab
 
#Click on ''New'' just below the Groups table
 
#Click on ''New'' just below the Groups table
#Enter the name of the group. We call it '''bundle.jars'''
+
#Enter the name of the group, i.e. '''Basic'''
 
#For each feature that should be included in this group
 
#For each feature that should be included in this group
 
##Click on ''New'' just next to the prerequisites table
 
##Click on ''New'' just next to the prerequisites table
 
##Select a feature from the drop down menu.
 
##Select a feature from the drop down menu.
##Enter the name '''bundle.jars'''
+
##Enter the name <font color=blue>'''feature.jars'''</font>
 
##Click OK
 
##Click OK
  
If you follow the example, you now have four groups, Basic, Optional, feature.jars, and bundle.jars.
+
Repeat these steps for the '''Optional''' group.
  
===The Action===
+
Attributes, Groups, and Actions are all ''Attributes'' in Buckminster terms. A group contains attributes. Subsequently, a group can include other groups. This allows for a simplification of the '''feature.jars''' group that we created earlier. Instead of having that group include all features, it could instead include the two category groups, i.e. instead of having:
 +
<pre>
 +
feature.jars
 +
  a[feature.jars]
 +
  b[feature.jars]
 +
  c[feature.jars]
 +
  d[feature.jars]
 +
 
 +
Basic
 +
  a[feature.jars]
 +
  b[feature.jars]
 +
 
 +
Optional
 +
  c[feature.jars]
 +
  d[feature.jars]
 +
</pre>
 +
we can simplify and do
 +
<pre>
 +
feature.jars
 +
  [Basic]
 +
  [Optional]
 +
 
 +
Basic
 +
  a[feature.jars]
 +
  b[feature.jars]
 +
 
 +
Optional
 +
  c[feature.jars]
 +
  d[feature.jars]
 +
</pre>
 +
(the example assumes that a, b, c, and d are features and [xxx] denotes attribute xxx)
 +
 
 +
If you follow the example (simplification or not), you now have four groups, Basic, Optional, feature.jars, and bundle.jars.
 +
 
 +
====The Action====
 
The last thing to add to the CSPEC is the Action that will trigger the actual build of the update site.
 
The last thing to add to the CSPEC is the Action that will trigger the actual build of the update site.
 
#Click on the Actions tab
 
#Click on the Actions tab
Line 93: Line 299:
 
##Enter the name '''build.site'''
 
##Enter the name '''build.site'''
 
##Put a check mark the ''Public'' checkbox
 
##Put a check mark the ''Public'' checkbox
##Enter the ''Actor Name:'' '''ant'''
+
##Enter the ''Actor Name:'' <font color=blue>'''ant'''</font>
 
#Adding the site.template prerequisite
 
#Adding the site.template prerequisite
 
##Click on the ''New'' button next to the ''Prerequisites'' table
 
##Click on the ''New'' button next to the ''Prerequisites'' table
 
##Leave ''Component'' blank (this means current component)
 
##Leave ''Component'' blank (this means current component)
 
##Select '''site.template''' from the ''Attribute'' combobox
 
##Select '''site.template''' from the ''Attribute'' combobox
##Enter the ''Alias'' name '''template'''
+
##Enter the ''Alias'' name <font color=blue>'''template'''</font>
 
##Click OK
 
##Click OK
 
#Adding the rootFiles prerequisite
 
#Adding the rootFiles prerequisite
Line 104: Line 310:
 
##Leave ''Component'' blank
 
##Leave ''Component'' blank
 
##Select '''site.rootFiles''' from the ''Attribute'' combobox
 
##Select '''site.rootFiles''' from the ''Attribute'' combobox
##Enter the ''Alias'' name '''rootFiles'''
+
##Enter the ''Alias'' name <font color=blue>'''rootFiles'''</font>
 
##Click OK
 
##Click OK
 
#Adding the features
 
#Adding the features
Line 110: Line 316:
 
##Leave ''Component'' blank
 
##Leave ''Component'' blank
 
##Select '''feature.jars''' from the ''Attribute'' combobox
 
##Select '''feature.jars''' from the ''Attribute'' combobox
##Enter the ''Alias'' name '''features'''
+
##Enter the ''Alias'' name <font color=blue>'''features'''</font>
 
##Click OK
 
##Click OK
 
#Adding the plugins
 
#Adding the plugins
Line 116: Line 322:
 
##Leave ''Component'' blank
 
##Leave ''Component'' blank
 
##Select '''bundle.jars''' from the ''Attribute'' combobox
 
##Select '''bundle.jars''' from the ''Attribute'' combobox
##Enter the ''Alias'' name '''plugins'''
+
##Enter the ''Alias'' name <font color=blue>'''plugins'''</font>
 
##Click OK
 
##Click OK
 
#Adding general properties. These properties control the general behavior.
 
#Adding general properties. These properties control the general behavior.
 
##In the middle pane, click on ''Properties''
 
##In the middle pane, click on ''Properties''
 
##Click on ''New'' next to the ''General Properties'' table
 
##Click on ''New'' next to the ''General Properties'' table
##Enter ''Key'' '''site.name''' and a value such as '''test.archivedsite'''
+
##Enter ''Key'' <font color=blue>'''site.name'''</font> and a value such as '''test.archivedsite'''
 
##Click OK
 
##Click OK
 
##If you want your site to have some extra suffix such as ''_incubation'' then:
 
##If you want your site to have some extra suffix such as ''_incubation'' then:
 
###Click on ''New'' next to the ''General Properties'' table
 
###Click on ''New'' next to the ''General Properties'' table
###Enter ''Key'' '''site.extra.suffix''' and a value such as '''_incubation'''
+
###Enter ''Key'' <font color=blue>'''site.extra.suffix'''</font> and a value such as '''_incubation'''
 
###Click OK
 
###Click OK
 
#Adding actor properties. These properties control behavior specific to an actor. We need two of them. One to specify the ant build script that will be used and another to specify what ant target to call in that file.
 
#Adding actor properties. These properties control behavior specific to an actor. We need two of them. One to specify the ant build script that will be used and another to specify what ant target to call in that file.
 
##Click on ''New'' next to the ''Actor Properties'' table
 
##Click on ''New'' next to the ''Actor Properties'' table
##Enter ''Key'' '''buildFileId''' and the value '''buckminster.pdetasks'''
+
##Enter ''Key'' <font color=blue>'''buildFileId'''</font> and the value <font color=blue>'''buckminster.pdetasks'''</font>
 
##Click OK
 
##Click OK
 
##Click on ''New'' again
 
##Click on ''New'' again
##Enter ''Key'' '''targets''' and the value '''create.site'''
+
##Enter ''Key'' <font color=blue>'''targets'''</font> and the value <font color=blue>'''create.legacy.site'''</font> (in releases prior to 3.5 this target was called <font color=blue>'''create.site'''</font>)
 
##Click OK
 
##Click OK
 
#Finally, we must specify the product of this action and give it an alias that it passes on to Ant.
 
#Finally, we must specify the product of this action and give it an alias that it passes on to Ant.
 
##Click on ''Products'' in the middle pane.
 
##Click on ''Products'' in the middle pane.
##Enter the ''Product Alias'' '''action.output'''
+
##Enter the ''Product Alias'' <font color=blue>'''action.output'''</font>
 
##Enter the ''Product Base Path'' '''site/'''
 
##Enter the ''Product Base Path'' '''site/'''
  
Line 145: Line 351:
  
 
The output will end up in ${user.temp}/buckminster by default. You can change this by setting the property '''buckminster.output.root''' in a property file that you reference when you execute the action. You can also specify properties using ''Windows'' -> ''Preferences'' -> ''Run/Debug'' -> ''String substitution''.
 
The output will end up in ${user.temp}/buckminster by default. You can change this by setting the property '''buckminster.output.root''' in a property file that you reference when you execute the action. You can also specify properties using ''Windows'' -> ''Preferences'' -> ''Run/Debug'' -> ''String substitution''.
 +
 +
==Headless builds==
 +
The site can also be built from the command line using a headless setup. Simply issue the command:
 +
<pre>
 +
buckminster -d <your workspace> perform org.test.update#build.site
 +
</pre>
 +
 +
 +
[[Category:Buckminster]]
 +
[[Category:Buckminster Tutorial]]
 +
[[Category:Buckminster Usecases]]
 +
[[Category:Buckminster Examples]]

Latest revision as of 04:59, 20 August 2009

This is a step by step instruction on how to create an update site using Buckminster. It assumes that you already have some features that you want to include on the site and that you have the Buckminster core and pde support installed in the IDE.

Contents

[edit] P2 repositories using the 3.5 release and beyond

Buckminster recognizes a normal Eclipse Feature as a valid description of a P2 enabled site. Actions has been added to the feature so that a P2 site can be built automatically. The build can include steps to normalize, sign, and pack the site.

The process is very simple.

  1. Create a feature project
  2. Add all features that you want published to the site
  3. Add categorization to the build.properties
  4. Build the site

[edit] The feature.xml file

The content of the feature.xml file is used like this:

feature.xml generated repository
Label Name of the metadata repository
Included features Root IU's
Discovery sites Site references
Mirrors Site Mirrors Site

Please note that since this feature is a description of the site as a whole, it is not included in the generated site.

[edit] The build.properties file

Some additional information (such as categories) can be provided in the build.properties file. An editor pane for this file is already readily available in the standard PDE feature editor.

[edit] Category declaration

A category is declared like this:

category.id.<category id>=<category label>

Example:

category.id.core=Buckminster (core)

[edit] Category membership

Category membership is declared as:

category.members.<category id>=<feature id>[,<feature id>]*

Example:

category.members.core=org.eclipse.buckminster.core.feature
category.members.optional=org.eclipse.buckminster.cvs.feature,org.eclipse.buckminster.svn.feature,...

[edit] Category description

It is also possible to add a category description as:

category.description.<category id>=<A verbose description of the category>

Example:

category.description.buckminster=This is the category that contains Buckminster core functionality

[edit] The default category

A default category can be used for capturing all included features not covered by membership:

category.default=<category id>

[edit] Translations

All category fields are subject to translation via the feature.properties file. Example:

category.description.buckminster=%CoreCategoryDesc

In feature.properties:

CoreCategoryDesc=This is the category that contains Buckminster core functionality

[edit] The properties provided when building

Properties that controls the build can be provided in three different ways:

  1. As a separate properties file referenced when you execute the build
  2. As system properties, i.e. -Dxxx=yyy on the command line
  3. As preferences in your workspace using Windows -> Preferences -> Run/Debug -> String substitution

The properties that are relevant for the site generation are:

Name Value Example
buckminster.output.root Absolute path in the local filesystem that controls the output of the build /home/bertil/build.output
buckminster.temp.root Absolute path in the local filesystem that controls where temporary content ends up during the build /home/bertil/tmp/build.tmp
eclipse.committer.name Only applicable to Eclipse signing Committer name used when doing signing at Eclipse.org. This committer must have signing priviligies bertil
eclipse.committer.password Only applicable to Eclipse signing Password for the eclipse committer blue$25x
local.keystore.path Only applicable to local signing Absolute path in the local filesystem that appoints your personal certificate /home/bertil/certificates/personal.certificate
local.keystore.alias Alias used by the local keystore thomas
local.keystore.password Password for the local keystore kitty123
site.pack200 A boolean value controlling pack200 (and normalization if signing is enabled true or false
site.signing A boolean value controlling signing true or false
signing.type The type of signing to use. Can be either eclipse.remote (requires Eclipse committer credentials) or local (requires local certificate) eclipse.remote

[edit] The eclipse.remote signing

This is a special type of signing added to support builds intended to be released at the eclipse.org download site. The signing requires that the one who runs the action can provide credentials for an eclipse committer that has signing privileges.

If enabled, the build will package all relevant jars in a zip file and send it over to Eclipse.org using scp. It will request them to be signed by adding them to the queue for the Eclipse signer and then await the result. Once the signing is complete, it will be picked up and the build will continue. Although sometimes a bit slow (more then 20 minutes is rare), the process is fully automatic and does not require any manual intervention.

[edit] Using local signing

Local signing can be used by anyone interested in signing the jars that are included in the generated site. To use this, you must create a personal certificate. This is done with the keytool executable. You will find it in the bin catalog of your JDK.

Type in:
keytool -genkeypair -keystore <path to keystore file> -alias <your alias>
Suggestions:
<path to keystore file> /home/bertil/certificates/personal.certificate
<your alias> A short name like 'bertil', 'betty', etc.

You will be asked for some information about name, location, and password. Enter some sane values. Finally you will be asked to confirm the information and you are then asked if you want the same password as for the keystore - simply hit return, you do not want an additional password.

[edit] Building the site

Right-click on your project, select Buckminster -> Invoke action -> site.p2

[edit] Headless builds

The site can also be built from the command line using a headless setup. Simply issue the command:

buckminster -d <your workspace> perform org.test.update#site.p2

[edit] Tips

If you encounter problems to build your update site, please check file META-INF/MANIFEST.MF of all your plugins included in your features.

The MANIFEST.MF shall contains following line:

 Bundle-ManifestVersion: 2

If not, add it to your file. Then apply all proposed quick fixes to have a full compliant manifest, at the end there should be no warnings (at least for MANIFEST.MF).

[edit] Legacy Update sites

[edit] Creating the Update Site Project

To Buckminster, an update site is not different from any other type of component. We need to keep the definition of the update site in a project, and we need some additional meta data to enable convenient building of the site. The first step is to create the update site project:

  1. Right click in the Package Explorer and select New -> Project
  2. In the New Project wizard that pops up, open the Plug-in Development folder
  3. Click on Update Site Project
  4. Give the project a name. In this example we use org.test.update
  5. Click on Finish

The project appears in the workspace and it contains one single file, an empty site.xml. Buckminster will use this as the update site template. This means that you can add site categories to this file but you should not add any features. Buckminster will generate a new site.xml where the features are added.

[edit] Creating an index.html file

Just create an empty file in the root folder of your new update site project for now and call it index.html. You can add content to this file that will be what the user will see if they happen to access your update site with a browser.

[edit] Creating the Component Specification

Buckminster describes all components in terms of CSPECs. The update site is no exception. Here are the steps to create such a CSPEC and enter the needed information:

  1. Right click on the update site project and select New -> Other
  2. In the New wizard that pops up, open the Buckminster folder
  3. Select Component Specification file and click on Next
  4. Click on Finish to accept the default values for Container: and File name:

A file named buckminster.cspec is created in the project and the Buckminster CSPEC editor opens. Do not change the name of this file.

[edit] Main information

  • The name of the component is normally the same as the name of the project. This makes it easier to find the component.
  • The component type must in our case be set to buckminster.
  • The version can be any OSGi compliant version such as 1.0.0

[edit] Artifacts

Artifacts denotes files and folders that are present inside of a component. The action that will create the update site needs to know about the site.xml template and other files to copy so we need to add that to our specification:

  1. Click on the Artifacts tab
  2. Click on New below the Artifacts table
  3. Enter a name such as site.template
  4. Click on the New button next to the Path table
  5. Enter the name site.xml in the dialog that pops up and click OK
  6. Click on New below the Artifacts table
  7. Enter the name site.rootFiles
  8. Click on the New button next to the Path table
  9. Enter the name index.html in the dialog that pops up and click OK

We now have two artifacts, each with one path. The separation is necessary in this particular case since the build action will reference the artifacs separately. An artifact may have several paths and you can add as many files and folders as you wish to the site.rootFiles artifact.

[edit] Dependencies

We need to define the features that will be included on the update site. Buckminster considers them to be dependencies:

  1. Click on the Dependencies tab
  2. For each feature that you want to add, repeat the following:
    1. Click on New just next to the Dependencies table
    2. Enter the name of a feature component
    3. Set the Component Type to eclipse.feature
    4. Click OK

[edit] Groups

The build action will expect one prerequisite that lists all the feature jars and one that lists all plugin jars. Luckily for us, Buckminster has already generated CSPEC's for all features with attributes that will provide just that. A feature will always have the two public attributes:

  • feature.jars
This is the transitive closure of all features (including the feature itself) in jared format.
  • bundle.jars
This is all the plugins that the transitive closure of all features is referencing in jared format.

Since we don't have a feature that describes the update site itself, we need to create two new groups. One that group all the feature.jars together, and one that group all the bundle.jars together.

  1. Click on New just below the Groups table
  2. Enter the name of the group. We call it feature.jars
  3. For each feature that should be included in this group
    1. Click on New just next to the prerequisites table
    2. Select a feature from the drop down menu.
    3. Enter the name feature.jars
    4. Click OK

Repeat these steps for a group that is called bundle.jars that references the bundle.jars attribute of each feature.

[edit] Defining Site Categories

This step is optional unless you want to categorize the contents of the update site. In order to define a Site Category, you must first create the category in the site.xml file and then add it as a group in the CSPEC.

In order to create a category in the site.xml file, do the following:

  1. Double click on the site.xml file. The Update Site Editor opens
  2. On the Site Map tab, click New Category
  3. Give the category a name. In this example we will use Basic
  4. Add a label such as Basic features

Repeat these steps and create an additional categogy named Optional with label Optional features

Back to the CSPEC editor:

  1. Click on the Groups tab
  2. Click on New just below the Groups table
  3. Enter the name of the group, i.e. Basic
  4. For each feature that should be included in this group
    1. Click on New just next to the prerequisites table
    2. Select a feature from the drop down menu.
    3. Enter the name feature.jars
    4. Click OK

Repeat these steps for the Optional group.

Attributes, Groups, and Actions are all Attributes in Buckminster terms. A group contains attributes. Subsequently, a group can include other groups. This allows for a simplification of the feature.jars group that we created earlier. Instead of having that group include all features, it could instead include the two category groups, i.e. instead of having:

feature.jars
  a[feature.jars]
  b[feature.jars]
  c[feature.jars]
  d[feature.jars]

Basic
  a[feature.jars]
  b[feature.jars]

Optional
  c[feature.jars]
  d[feature.jars]

we can simplify and do

feature.jars
  [Basic]
  [Optional]

Basic
  a[feature.jars]
  b[feature.jars]

Optional
  c[feature.jars]
  d[feature.jars]

(the example assumes that a, b, c, and d are features and [xxx] denotes attribute xxx)

If you follow the example (simplification or not), you now have four groups, Basic, Optional, feature.jars, and bundle.jars.

[edit] The Action

The last thing to add to the CSPEC is the Action that will trigger the actual build of the update site.

  1. Click on the Actions tab
  2. Adding General action information
    1. Click on New below the Actions table
    2. Enter the name build.site
    3. Put a check mark the Public checkbox
    4. Enter the Actor Name: ant
  3. Adding the site.template prerequisite
    1. Click on the New button next to the Prerequisites table
    2. Leave Component blank (this means current component)
    3. Select site.template from the Attribute combobox
    4. Enter the Alias name template
    5. Click OK
  4. Adding the rootFiles prerequisite
    1. Click on the New button next to the Prerequisites table
    2. Leave Component blank
    3. Select site.rootFiles from the Attribute combobox
    4. Enter the Alias name rootFiles
    5. Click OK
  5. Adding the features
    1. Click on the New button next to the Prerequisites table
    2. Leave Component blank
    3. Select feature.jars from the Attribute combobox
    4. Enter the Alias name features
    5. Click OK
  6. Adding the plugins
    1. Click on the New button next to the Prerequisites table
    2. Leave Component blank
    3. Select bundle.jars from the Attribute combobox
    4. Enter the Alias name plugins
    5. Click OK
  7. Adding general properties. These properties control the general behavior.
    1. In the middle pane, click on Properties
    2. Click on New next to the General Properties table
    3. Enter Key site.name and a value such as test.archivedsite
    4. Click OK
    5. If you want your site to have some extra suffix such as _incubation then:
      1. Click on New next to the General Properties table
      2. Enter Key site.extra.suffix and a value such as _incubation
      3. Click OK
  8. Adding actor properties. These properties control behavior specific to an actor. We need two of them. One to specify the ant build script that will be used and another to specify what ant target to call in that file.
    1. Click on New next to the Actor Properties table
    2. Enter Key buildFileId and the value buckminster.pdetasks
    3. Click OK
    4. Click on New again
    5. Enter Key targets and the value create.legacy.site (in releases prior to 3.5 this target was called create.site)
    6. Click OK
  9. Finally, we must specify the product of this action and give it an alias that it passes on to Ant.
    1. Click on Products in the middle pane.
    2. Enter the Product Alias action.output
    3. Enter the Product Base Path site/

This concludes the CSPEC editing. Save it using CTRL-s or File -> Save

[edit] Building the site

Right-click on your project, select Buckminster -> Invoke action -> build.site

The output will end up in ${user.temp}/buckminster by default. You can change this by setting the property buckminster.output.root in a property file that you reference when you execute the action. You can also specify properties using Windows -> Preferences -> Run/Debug -> String substitution.

[edit] Headless builds

The site can also be built from the command line using a headless setup. Simply issue the command:

buckminster -d <your workspace> perform org.test.update#build.site