Difference between pages "Details for Uploading Main Rodin Update Site" and "Developer FAQ"

From Event-B
(Difference between pages)
Jump to navigationJump to search
imported>Tommy
 
imported>Jrloria
(from FAQ)
 
Line 1: Line 1:
Since April 5th, 2012, the Rodin update site has the newer p2 format.
+
== How to contribute? ==
From a release engineer point of view, the main change is that instead of uploading 'site.xml' to the rodin web space, you will just commit 'content.jar' and 'artifacts.jar' to SVN. This page explains how to generate these two files.
+
See the [[How_To_Contribute|How to contribute]] page.
If you're interested in internal details, you can take a look at [[How we set up the p2 update site on SourceForge]].<br>
 
There are some [[Details_for_Maintaining_Main_Rodin_Update_Site#Rules_to_follow | few rules to follow when providing contents to the main Rodin update site]], please take a look at them.
 
  
== Using site.xml ==
+
== Developer FAQ ==
 +
=== How can I get the sources of the Rodin platform? ===
  
Even though 'site.xml' is no more present on the remote update site, it can be used locally to publish new features (or new versions of existing features).
+
There are two options for getting the sources of the Rodin platform:
 +
# The safe option is to download the source bundle which is made available with each platform release.  This ensures that you will get a consistent set of source files, albeit maybe a bit outdated.
 +
# The other option is to fetch the sources from Subversion, which allows to get their latest version.  The Rodin developers strive for keeping theses sources usable (i.e. they should always compile and pass unit tests), but breakage can happen.
  
# make sure your workspace copy of the plugin project org.rodinp.updateSite is synchronised with the SVN repository.
+
=== Installing the source bundle in Eclipse ===
# open 'site.xml' with the Site Manifest Editor
 
# add your feature to the relevant category (no need to give artifact url)
 
# click 'Build': 'content.jar' and 'artifacts.jar' get updated, 'features' and 'plugins' directories are created (do NOT click 'Build All', it would overwrite the update site !)
 
# test locally, using org.rodinp.updateSite as local update site; in particular, check that other plug-ins on the update site are still listed
 
# upload the jars generated by the build as usual in your plugin's area on [http://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download SourceForge FRS]
 
# test remotely by uploading 'content.jar' and 'artifacts.jar' to /home/project-web/rodin-b-sharp/htdocs/test-updates on the rodin web space, and using 'http://rodin-b-sharp.sourceforge.net/test-updates' as remote update site (see [[#Remote test]])
 
# commit 'content.jar' and 'artifacts.jar' to SVN: it actually updates the Rodin Update Site itself
 
# test using the standard Rodin Update Site (you may need to reload it)
 
  
So 'site.xml' is no more uploaded nor committed to SVN, it is really just there to help working with 'content.jar' and 'artifacts.jar'. In particular, if for some reason you want to commit it nevertheless, take care not to commit the post 'Build' version, as it mixes everything up.
+
To install the bundled sources, you first have to download the bundle from SourceForge. It takes the form of a ZIP file named <tt>rodin-VERSION-sources.zip</tt>. Then, in Eclipse, click {{Menu|File > Import...}}  In the ''Import'' popup, select {{Menu|General > Existing Projects into Workspace}} and click {{button|Next}}.  Then tick {{Menu|Select archive file}} and enter the path to the source bundle you have just downloaded.  Ensure that all projects are ticked and click {{button|Finish}}.  Your workspace gets populated with the source projects of the Rodin platform and Eclipse starts building.
  
== Externally built feature ==
+
=== Installing the sources from Subversion in Eclipse ===
  
That's the scripted way to proceed. If you are using scripts to build your feature (that is, without a running eclipse interface):
+
To install the sources from Subversion, in Eclipse click {{Menu|File > Import...}}, then select {{Menu|SVN > Checkout Projects from SVN}} in the ''Import'' popup and click {{button|Next}} twice. In the ''Url'' textbox, enter <tt>https://rodin-b-sharp.svn.sourceforge.net/svnroot/rodin-b-sharp</tt> and click {{button|Next}}. In the tree displaying the subversion repository, select path <tt>trunk/RodinCore/org.rodinp.releng</tt> and click {{button|Finish}}. Your workspace now contains the project <tt>org.rodinp.releng</tt>.
# ensure that your build scripts produce a repository (like 'buildRepo')
 
# categorize the repository (see below)
 
# launch the 'publishFeature.xml' ant script in org.rodinp.updateSite on the categorized repository (modifying the 'featureRepo' property in the launch config) to update 'content.jar' and 'artifacts.jar'.
 
Messages like
 
  [p2.mirror] Problems resolving provisioning plan.
 
  [p2.mirror] Unable to satisfy dependency from <my plugin> to bundle org.eventb.ui 0.0.0.
 
are normal, it just indicates that the repository does not contain core bundles.
 
  
From this point, continue the same as with 'site.xml', from 'test locally' on.
+
To install the other source projects, click again {{Menu|File > Import...}}, but this time select {{Menu|Team > Team Project Set}} and click {{button|Next}}.  When asked for a ''File name'', enter the path to file <tt>org.rodinp.releng/rodin-core.psf</tt> in your workspace and click {{button|Finish}}.  Eclipse then fetches the other source projects of the Rodin platform into your workspace (this can take some time).
  
=== Categorizing a build repository ===
+
=== Using Rodin-SVN from Eclipse consumes too much memory ===
 +
Running the Rodin platform from Eclipse can consume a lot of RAM and become impractical on a small machine.  If you fall in this case, you can [[#How_do_I_generate_a_Rodin_product_from_SVN.3F|generate a product]] and use it as if it was a normal release.
  
Build repositories are not categorized by default. To assign a built feature a category, we have to use the Category Publisher:
+
=== How do I generate a ''Rodin'' product from sources? ===
# copy the build repository somewhere, we'll call that somewhere $REPO (it ensures you can relaunch categorization if something goes wrong, without rebuilding your feature)
+
In the project ''org.rodinp.platform'', right-click on ''Rodin.platform'' and select {{menu|export}}. Choose {{menu|Plug-in Development > Eclipse product}} and click on {{button|Next}} type <tt>Rodin</tt> for the ''Root directory'', and choose the ''Destination directory''. Then click on {{button|Finish}}.
# write a category file
 
# run the Category Publisher
 
  
To make things concrete, here are sample files for categorizing the B2LaTeX plug-in:
+
=== How to build ''Rodin'' headless? ===
 +
When releasing a new version of the Rodin platform, the Rodin team builds the platform headless (i.e. using batch scripts rather than Eclipse GUI).  The process used for that is described in [[Building Rodin Headless]].  Alternatively, the Rodin team has also set up a [[CruiseControl]] server for checking that builds do not break.
  
category.xml:
+
=== How do I collect debug information from the Rodin platform? ===
<?xml version="1.0" encoding="UTF-8"?>
+
You may see the log in the console by appending <tt>-consoleLog</tt> to the rodin executable: <code>rodin -consoleLog</code>
<site>  
 
  <feature id="ac.soton.eventb.latex.feature">
 
    <category name="Utilities"/>  
 
  </feature>  
 
  <category-def name="Utilities" label="Utilities"/>
 
</site>  
 
  
catPub.sh:
+
You may add specific debug informations by setting specific options: <code>rodin --debug options.file -consoleLog</code> where {{file|options.file}} contains something like:
JAVA_HOME=/usr/lib/jvm/java-6-sun/jre
+
<pre>
ECLIPSE_HOME=/path/to/eclipse
+
org.pluginname/debug = true
REPO=/path/to/buildRepo/copy
+
org.pluginname/debug/optionaldebug = true
CAT_FOLDER=/path/to/category/folder
+
</pre>
+
where'' optionaldebug'' may be found in the {{file|org.pluginname/.options}} file in the [http://rodin-b-sharp.cvs.sourceforge.net/rodin-b-sharp/ rodin source repository].
$JAVA_HOME/bin/java \
 
        -jar $ECLIPSE_HOME/plugins/org.eclipse.equinox.launcher_*.jar \
 
        -application org.eclipse.equinox.p2.publisher.CategoryPublisher \
 
        -metadataRepository file:/$REPO \
 
        -categoryDefinition file:/$CAT_FOLDER/category.xml
 
  
== Remote test ==
+
=== How do I submit a patch? ===
Copy 'content.jar' and 'artifacts.jar' from your eclipse workspace to you user home directory (this just makes it easier to locate the file from the terminal command line since the user home directory is the default local directory in Terminal)
+
Good practises for patch submission are described [[How to Submit Patches|here]].
Open the Terminal utility and enter the following commands replacing <sourceforgeusername> and <sourceforgepassword>:
 
  
Last login: Tue May 17 21:22:29 on console
+
=== How do I track memory leaks? ===
dhcp-152-78-95-201:~ <localusername>$ sftp <sourceforgeusername>,rodin-b-sharp@web.sourceforge.net
+
If you suspect that some memory isn't freed, you may find some useful directions on how to track memory leaks [[Tracking Memory Leaks|here]].
Connecting to web.sourceforge.net...
 
<sourceforgeusername>,rodin-b-sharp@web.sourceforge.net's password: <sourceforgepassword>
 
sftp> cd htdocs
 
sftp> cd test-updates
 
sftp> ls -a
 
.          ..        .htaccess
 
sftp> put content.jar
 
Uploading content.jar to /home/project-web/rodin-b-sharp/htdocs/test-updates/content.jar
 
content.jar                                                                                                                                            100%  82KB  82.3KB/s  00:01   
 
sftp> put artifacts.jar
 
Uploading artifacts.jar to /home/project-web/rodin-b-sharp/htdocs/test-updates/artifacts.jar
 
artifacts.jar                                                                                                                                          100% 8975    8.8KB/s  00:00   
 
  
You can then try this remote update site from a running Rodin platform.
+
=== How do I report a bug. ===
To do this, just add the remote site to the list of available sites (which will look like below)
+
See [[How_To_Contribute#How_do_I_report_a_bug_or_a_feature_request.3F|the ''How to contribute'' page]].
Rodin Remote Test Update Site - http://rodin-b-sharp.sourceforge.net/test-updates
 
and select it.
 
  
The .htaccess file redirects plugins/*.jar and features/*.jar requests to SourceForge FRS, thus using the archives that you have uploaded.<br>
+
=== How do I save the models ? ===
 +
After the separation between a file ({{class|IRodinFile}}) and its root (a {{class|IInternalElement}}), that occurred in version 0.9.2, model saving is no more achievable through internal elements. Instead, you have to save the {{class|IRodinFile}}.
  
'''Once the test is complete, please remove the jars:'''
+
  IInternalElement element = ...
  sftp> rm *.jar
+
  element.getRodinFile().save(...);
  Removing /home/project-web/rodin-b-sharp/htdocs/test-updates/artifacts.jar
 
Removing /home/project-web/rodin-b-sharp/htdocs/test-updates/content.jar
 
 
  
  
 +
=== How do I add a new attribute to existing elements (e.g. Event-B event)? ===
 +
You need to extend the following extension point <code>org.rodinp.core.attributeTypes</code> to declare the new attribute.
  
[[Category:Developer documentation|*Index]]
+
Note: There is no constraint on which element type this attribute type associated with. In principle, any attribute type can be attached to the any internal element type.
[[Category:Rodin Platform|*Index]]
+
 
 +
The detail steps are described in the following page [[Extending the Rodin Database#Adding a New Attribute|Extending the Rodin Database]].
 +
 
 +
=== How do I extend the Event-B structure editor (the Edit Tab of the Event-B editor) for editing an attribute (which I added to the Rodin DB as described [[#How do I add a new attribute to existing elements (e.g. Event-B event)?| here]])? ===
 +
 
 +
You need to extend the following extension point <code>org.eventb.ui.editorItems</code> to declare the two different elements:
 +
 
 +
* How the attribute is going to be displayed/edited. This is done by declaring one of the following elements: <code>textAttribute</code>, <code>choiceAttribute</code> or <code>toggleAttribute</code>.
 +
 
 +
* The relationship between the attribute and internal elements. This is done by declaring an <code>attributeRelation</code> element.  Note: In fact, this relationship declares which element '''allows''' to have this attribute, which is not something enforce when the attribute is added as described [[#How do I add a new attribute to existing elements (e.g. Event-B event)?| here]].
 +
 
 +
The detail steps are described in the following page [[Extending the Structure Editor#Adding a New Attribute|Extending the Structure Editor]].
 +
 
 +
 
 +
[[Category:Developer FAQ]]

Revision as of 10:12, 26 March 2010

How to contribute?

See the How to contribute page.

Developer FAQ

How can I get the sources of the Rodin platform?

There are two options for getting the sources of the Rodin platform:

  1. The safe option is to download the source bundle which is made available with each platform release. This ensures that you will get a consistent set of source files, albeit maybe a bit outdated.
  2. The other option is to fetch the sources from Subversion, which allows to get their latest version. The Rodin developers strive for keeping theses sources usable (i.e. they should always compile and pass unit tests), but breakage can happen.

Installing the source bundle in Eclipse

To install the bundled sources, you first have to download the bundle from SourceForge. It takes the form of a ZIP file named rodin-VERSION-sources.zip. Then, in Eclipse, click File > Import... In the Import popup, select General > Existing Projects into Workspace and click Next. Then tick Select archive file and enter the path to the source bundle you have just downloaded. Ensure that all projects are ticked and click Finish. Your workspace gets populated with the source projects of the Rodin platform and Eclipse starts building.

Installing the sources from Subversion in Eclipse

To install the sources from Subversion, in Eclipse click File > Import..., then select SVN > Checkout Projects from SVN in the Import popup and click Next twice. In the Url textbox, enter https://rodin-b-sharp.svn.sourceforge.net/svnroot/rodin-b-sharp and click Next. In the tree displaying the subversion repository, select path trunk/RodinCore/org.rodinp.releng and click Finish. Your workspace now contains the project org.rodinp.releng.

To install the other source projects, click again File > Import..., but this time select Team > Team Project Set and click Next. When asked for a File name, enter the path to file org.rodinp.releng/rodin-core.psf in your workspace and click Finish. Eclipse then fetches the other source projects of the Rodin platform into your workspace (this can take some time).

Using Rodin-SVN from Eclipse consumes too much memory

Running the Rodin platform from Eclipse can consume a lot of RAM and become impractical on a small machine. If you fall in this case, you can generate a product and use it as if it was a normal release.

How do I generate a Rodin product from sources?

In the project org.rodinp.platform, right-click on Rodin.platform and select export. Choose Plug-in Development > Eclipse product and click on Next type Rodin for the Root directory, and choose the Destination directory. Then click on Finish.

How to build Rodin headless?

When releasing a new version of the Rodin platform, the Rodin team builds the platform headless (i.e. using batch scripts rather than Eclipse GUI). The process used for that is described in Building Rodin Headless. Alternatively, the Rodin team has also set up a CruiseControl server for checking that builds do not break.

How do I collect debug information from the Rodin platform?

You may see the log in the console by appending -consoleLog to the rodin executable: rodin -consoleLog

You may add specific debug informations by setting specific options: rodin --debug options.file -consoleLog where

options.file

contains something like:

org.pluginname/debug = true
org.pluginname/debug/optionaldebug = true

where optionaldebug may be found in the

org.pluginname/.options

file in the rodin source repository.

How do I submit a patch?

Good practises for patch submission are described here.

How do I track memory leaks?

If you suspect that some memory isn't freed, you may find some useful directions on how to track memory leaks here.

How do I report a bug.

See the How to contribute page.

How do I save the models ?

After the separation between a file (IRodinFile) and its root (a IInternalElement), that occurred in version 0.9.2, model saving is no more achievable through internal elements. Instead, you have to save the IRodinFile.

IInternalElement element = ...
element.getRodinFile().save(...);


How do I add a new attribute to existing elements (e.g. Event-B event)?

You need to extend the following extension point org.rodinp.core.attributeTypes to declare the new attribute.

Note: There is no constraint on which element type this attribute type associated with. In principle, any attribute type can be attached to the any internal element type.

The detail steps are described in the following page Extending the Rodin Database.

How do I extend the Event-B structure editor (the Edit Tab of the Event-B editor) for editing an attribute (which I added to the Rodin DB as described here)?

You need to extend the following extension point org.eventb.ui.editorItems to declare the two different elements:

  • How the attribute is going to be displayed/edited. This is done by declaring one of the following elements: textAttribute, choiceAttribute or toggleAttribute.
  • The relationship between the attribute and internal elements. This is done by declaring an attributeRelation element. Note: In fact, this relationship declares which element allows to have this attribute, which is not something enforce when the attribute is added as described here.

The detail steps are described in the following page Extending the Structure Editor.