Tutorial of developing and changing QuantumDb

Author: jparrai
Date: 28-03-2003
Subject: Tutorial of developing and changing QuantumDb

To modify the quantumdb plug-in, first you get it to a development system, usually Eclipse itself.

1. Getting the project from CVS.

First you go to Open a Perspective and open the CVS repository exploring perspective. It can be in the Others.... You get a perspective. You right-click on the CVS Repositories view and create a New -> Repository Location...
The data to access quantum is:

Host: cvs.sourceforge.net
Repository Path: /cvsroot/quantum
User: anonymous
Password:

There is no password for anonymous. You can substitute the User and Password for you own, if you are registered in sourcefoge.net. If you want developer access, remember to use extssh as the connexion type, so as to be able to update the cvs repository with your changes (that need a ssh connection in sourceforge)

After that, if you are connected to the Net, you will be able to get the project files. You will see a HEAD sub-item, a Branches, and a Versions. You select the HEAD, and then right-click onto quantum-plugin. Then select Check Out As.... You cannot check it out as a Project, because some files are not present, mainly the .project and .classpath.

2. Configuring the project.

So you "Check Out As..." and select an Plug-In project, call it as you wish, (I will use "com.quantum") and then select an Empty Plug In. If everything goes ok, you should end with a new project and about 1600 errors. The errors are caused because you have now a default classpath, and the quantumdb project uses some plug-ins, so these plug-ins directories must be referenced.

My classpath for Eclipse 2.0 is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
    <classpathentry kind="src" path="src"/>
    <classpathentry kind="var" path="JRE_LIB" rootpath="JRE_SRCROOT" sourcepath="JRE_SRC"/>
    <classpathentry kind="lib"
        path="C:/Parsec/eclipse/plugins/org.eclipse.core.boot_2.0.2/boot.jar" sourcepath="C:/Parsec/eclipse/plugins/org.eclipse.platform.source_2.0.2/src/org.eclipse.core.boot_2.0.2/bootsrc.zip"/>
    <classpathentry kind="lib"
        path="C:/Parsec/eclipse/plugins/org.eclipse.core.runtime_2.0.2/runtime.jar" sourcepath="C:/Parsec/eclipse/plugins/org.eclipse.platform.source_2.0.2/src/org.eclipse.core.runtime_2.0.2/runtimesrc.zip"/>
    <classpathentry kind="lib"
        path="C:/Parsec/eclipse/plugins/org.eclipse.core.resources_2.0.1/resources.jar" sourcepath="C:/Parsec/eclipse/plugins/org.eclipse.platform.source_2.0.2/src/org.eclipse.core.resources_2.0.1/resourcessrc.zip"/>
    <classpathentry kind="lib"
        path="C:/Parsec/eclipse/plugins/org.eclipse.swt.win32_2.0.2/ws/win32/swt.jar" sourcepath="C:/Parsec/eclipse/plugins/org.eclipse.platform.win32.source_2.0.2/src/org.eclipse.swt.win32_2.0.2/ws/win32/swtsrc.zip"/>
    <classpathentry kind="lib"
        path="C:/Parsec/eclipse/plugins/org.eclipse.ui_2.0.2/workbench.jar" sourcepath="C:/Parsec/eclipse/plugins/org.eclipse.platform.source_2.0.2/src/org.eclipse.ui_2.0.2/workbenchsrc.zip"/>
    <classpathentry kind="lib"
        path="C:/Parsec/eclipse/plugins/org.eclipse.ui.win32_2.0.0/workbenchwin32.jar"
        rootpath="" sourcepath="C:/Parsec/eclipse/plugins/org.eclipse.platform.win32.source_2.0.2/src/org.eclipse.ui.win32_2.0.0/workbenchwin32src.zip"/>
    <classpathentry kind="output" path="bin"/>
</classpath>

Where, as you can see, my Eclipse home is C:\Parsec\eclipse. In any case, you need to reference those plug-ins you see below, from org.eclipse:

core.boot
core.runtime
core.resources
ui
swt.win32 (substitute by your platform)
ui.win32 (substitute by your platform)

Remember after changing manually the .classpath file that you have to Refresh the project to take the changes in.

If you want to reference those plug-ins using the workspace, select Properties from the newly created com.quantum project and go to Java Build Path, then Libraries tab, and select the .jar files the project needs.

It should now build without errors.

In Eclipse 2.1 that won't work. Dependencies amongs plug-ins have changed and instead of redoing all of them again I chose to use the new "classpath container" facility. When I say that won't work I mean if linking against the 2.1 libraries. If you link against the 2.0 libraries will work all right.

The libraries for 2.1 are as follows (I copy my classpath) :

3. Running the project.

First go to Window -> Preferences -> Plug-in Development -> Target Platform and to select all the plug-ins that should be used when running a platform from the plug-in development. I select all of them not in the workspace because I don't want to resolve all the cross-references.

Then go to Run -> Run As -> Run-time Workbench. If all is well, a new workbench should appear, that has you just-compiled quantum plug-in installed. To check it, open the quantumdb perspective (Perspective Button -> Others... ->QuantumDb Perspective), and see if it appears. This is not
the usual QuantumDb perspective, but the one you are developing. Of course, if you have made no change to the standard source, there is no difference.

4. Making a small change.

To check that we are really using our modified QuantumDb, and not the standard, let's make a change. Open the QuantumResources.properties file, (in the com.quantum package), and modify the line

bookmarkview.newBookmark = New Bookmark...

to

bookmarkview.newBookmark = Add New Bookmark...

(for example)

Then Run the testing workbench again, you can now use simply Ctrl+F11 to run the last launched environment. Now, in the bookmark view, when you right-click on it, it should show your modified string. So you are now ready to change the plug-in.

5. Creating a .jar file.

You may simply want to make a .jar file from some configuration taken from the CVS, so as to have the latest version available to you. You have to follow the same instructions as before for installation. When it's installed and built, select the com.quantum project, right-click on it and select Export.

In Eclipse 2.0: Select jar File and then choose a directory. The name of the jar file should be Quantum.jar as that's the name stated in the plugin.xml file.

To install this jar file as a plug-in, create a directory called com.quantum in the directory plugins under your local Eclipse installation directory. Copy the jar file to that directory, and uncompress it (without deleting it) into that same directory. In fact, I think you only need the icons directory and the plugin.xlm, but you can leave the rest of the files so they feel not so alone.

You close your Eclipse IDE and open it up again, and the QuantumDB perspective should be available.

6. Uploading the change to CVS.

(I copy directly from the Eclipse Help, so as to have all the info in the same place)

Synchronizing with a CVS repository

In the CVS team programming environment, there are two distinct processes involved in synchronizing resources: updating with the latest changes from a branch and committing to the branch.

When you make changes in the Workbench, the resources are saved locally. Eventually you will want to commit your changes to the branch so others can have access to them. Meanwhile, others may have committed changes to the branch. You will want to update your Workbench resources with their changes.

Important!: It is preferable to update before committing, in case there are conflicts with the resources in your Workbench and the resources currently in the branch.

The synchronize view contains filters to control whether you want to view only incoming changes or outgoing changes. Incoming changes come from the branch. If accepted, they will update the Workbench resource to the latest version currently committed into the branch. Outgoing changes come from the Workbench. If committed, they will change the branch resources to match those currently present in the Workbench.

Regardless of which mode (filter) you select, the Synchronize view always shows you conflicts that arise when you have locally modified a resource for which a more recent version is available in the branch. In this situation you can choose to do one of three things: update the resource from the branch, commit your version of the resource to the branch ,or merge your work with the changes in the branch resource. Typically you will want to merge, as the other two options will result in loss of work.

(End of copy from Eclipse Help, there are lots more, just go there and have a look) Basically to get all the changes since the last time you took the sources, then accept all the files that have changed in the CVS and you haven't touched. If there are some that you have touched and are also touched by someone else at CVS then you have to inspect the changes, see if they conflict with yours, and merge both until you have a working set. Then you can upload that "working" set to CVS. That's more or less the idea.