Personal tools
You are here: Home / OSCAR EMR version 12.x / 4.0 Developers / 4.2 Installation 12.x / 4.2.5 IDE Install / 4.2.5.1 Oscar on Eclipse

4.2.5.1 Oscar on Eclipse

Developers will want to install Oscar on their favourite IDE. These are instructions for Eclipse.

Preface

These basic instructions are adequate for developing Oscar on Eclipse on Ubuntu using a deb install.  You can install Eclipse on any modern OS, but we encourage the better Open Source ones.   Eclipse is java based so if you want a newer version just untar it in your home folder. For other IDE's see Aart De Vries how to for installation on Netbeans (2009) 667Kb pdf.  Although his how to doesn't cover Git,  there now is an experimental plugin for Git on Netbeans called NBGit http://nbgit.org/ 

These instructions do not cover the where why and how of the Git content system, the wonders of Gerrit, nor how to actually use Eclipse: topics which are better covered elsewhere, and/or discovered on your own.

Document Version History

  • v1.0 – initial public release to oscarmanual.org– Feb 12, 2011
  • v1.1 – Maven step added – July 29, 2011
  • v1.2 – Added committing details – Sept 6, 2011
  • v1.3 – Added warning about serial commits – May 12, 2013
  • v1.4 – Reviewed installation against Eclipse version 4.3 Kepler – Dec 10, 2014
  • v1.5 – Updated to reflect Github login – Sept 22, 2015
The document is based on instructions from Ted Leung and is copyright © 2011-14 by Peter Hutten-Czapski under the Creative Commons Attribution-Share Alike 3.0 Unported License

 

Contents

  1. Preface
    1. Document Version History
  2. Register for Gerrit
  3. Installing Eclipse
  4. Installing EGit plugin
  5. Configuring the Plugin
  6. Cloning Oscar into Eclipse
  7. Making Changes
  8. When to commit and when to push

Register for Gerrit

We encourage every developer to sign up, even if you don't commit code right now, gerrit will give you the ability to view and comment on other committed patches etc.  You can register using your Github login.  Just navigate to (https://source.oscartools.org:8080/)

gerrit page

On the Gerrit main screen you should see a register option on the top right of the screen.

On the main registration screen :
    - For "Full Name" enter the persons name and click "save changed" (yes you actually need to click that now).
    - For "select a unique username" this will become your ssh access username, We'll use your email address (before the @ sign) as a standard. You need to click "select username" now.
    - For "Register an SSH public key" : if you already know or have SSH keys you can just provide it, otherwise do the following : 

~$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/peter/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/peter/.ssh/id_rsa.
Your public key has been saved in /home/peter/.ssh/id_rsa.pub.

Do not enter a passphrase when it asks. This means it will be easier for you to sign in AND... if you machine is compromised, your gerrit user is compromised and the corresponding server key should be deleted, you'll need to tell the gerrit administrator and or login to the gerrit web site and delete this key.

 Now cut and paste the contents of "~/.ssh/id_rsa.pub" into the text area on the web page.

SSH key

Click add and it should list it as an added key on the screen.
    - now on the bottom of the screen there's a link that says "continue" click that, now you should be at the your "code review dashboard" screen.

At this point, if your Eclipse was already running, you need to stop it and start it again. Eclipse caches ssh key information.

Installing Eclipse and Maven

First we need to install  Maven

sudo apt-get install maven2

Or, as you are in a GUI desktop environment anyway, use Synaptic to do the same thing

Synaptic

 

 

Now you need to install the EGit plugin

Installing EGit Plugin

Navigate to Eclipse  >  Help > Install New Software and add in

http://download.eclipse.org/egit/updates

add software

Press Add and OK

Install EGit

 

Now review what you are to install, Here we demonstrate we are installing version 0.10.1 of EGit

Install EGit2

 

 If you are installing Eclipse for the first time you will be asked to review and accept the licenses.

liscense

 

 and you will need to accept the veracity of the certificate

accept certificate

Configuring the Plugin

You will need a file in your home directory calls .gitconfig, which has a standard ini or property file structure.  Eclipse will generate it for you. 

  • Click Window > Preferences > Team > Git > Configuration
  • Click New Entry... and enter the key value pair user.email and your email that you registered on the gerrit site with
  • Click New Entry... and enter the key value pair user.name and your name
  • Other options such as core.editor can also be added
  • when you are done it should look like this:

EGit preferences

 

Cloning Oscar into Eclipse

Click File > Import... > Projects from Git > clone.

Import from Git

 

Add the Clone... (Kepler clone URI)

click on Clone

The repository details should be provided for your git/gerrit installation, 

You will want to use "ssh://xxxx@source.oscartools.org:29418/oscar". 

Just replace xxx with your Gerrit repository user name
Note that you do not need to enter a password. 

You can uncheck "Store in Secure Store" and you won't have to sign in every time you open Eclipse.

(BTW: The test repository shown below is just that.  Its a sandbox that you can use to get used to the "fetch" and "push" of it without worrying about anyone noticing.)

repository details

 You can select any branch,  but scroll down to find "master".

Select Master
You will be asked for the local destination.  You should accept the default unless you already have a directory of that name

destination

Then you will be asked for a secure password if you left the checkbox "store in a secure store" earlier

password

and then you will be cloning Oscar from master into your local repository

importing

Almost there

Almost done

[Next >] will determine how to share the imported project.  Lets use the defaults.

wizard

Identify the imported project by clicking on the checkbox

impoted project

Click the [Finish]  button and add Maven to your classpath

Window > Preferences > Java > Build Path > Classpath Variables > [New...]

Prior to adding the M2_REPO to Eclipse, you need to open a terminal and run mvn install command to create  /home/yourHomeDirectoryName/.m2

Add the M2_REPO and point it to your  /home/yourHomeDirectoryName/.m2/repository folder

Maven Classpath

 

and here you have it, Oscar in Eclipse

Oscar in Eclipse

For other Oscar projects  create a new workspace and repeat the above steps starting at "ssh://xxxx@source.oscartools.org:29418/{project}"

where {project} is taken from the available repositories such as

  • hhr
  • integrator
  • myoscar_client
  • myoscar_client2
  • myoscar_server
  • myoscar_server2
  • oscar_patient_portal
  • oscar
  • oscar_apps
  • oscar_documents
  • signature_pad
  • test
  • utils

Making Changes


Now say you've created new files in the project and altered some existing ones.

As a note, you should try to do a "team -> pull" before doing a commit, this will help ensure there are no commit conflicts, if there are your commit will not be mergable by gerrit and you'll have to go through a rebase of your commit before it can be merged. If you right click on the project, go to team > pull.

Team Pull


If you right click on the project, go to team > commit. You'll see the commit screen. Notice on eclipse it will list the tracked and untracked file and by default they will be "git added" and "git commited" at the same time. Now when you commit, it's commited locally. This means no one else except you has these changes still.
Team Commit

Add the information needed to identify the commit.

IMPORTANT: Commits should be labelled with the ID of the bug or Feature Request from Sourceforge that reflects the OSCAR Change request or Oscar bug that is being addressed.

Eclipse Commit

Now to share these changes with everyone else, i.e. committed to the main repository... (You must have committed locally first) 

Right click on the project, go to team -> push to upstream

Team Push to Upstream

A boring screen will show the uploading of file(s).

Eclipse is Pushing

If this is the first time you've pushed, you'll need to fill in a push specification according to if its going to the trunk or an established branch as below.

  • source ref="HEAD", destination ref="refs/for/master", 
  • source ref="HEAD", destination ref="refs/for/RELEASE_12_1",

select add spec, check the box on the bottom saying save spec... so you don't have to do this again. Just click "finish" (next doesn't show anything interesting).

Pushing details etc

Assuming you are pushing as above to the trunk (the "master" branch) after you have pushed the commit

If you go back to the gerrit web page you should see the change is pending review now as listed in Open.

Open pending Review in Gerrit

Note that at this point, you and the central repository are NOT in sync, the files at the central repository must be approved first.

  1. First the system will check the style of your code and attempt to build.  
  2. When that passes a check-mark will appear under the 'V'.  Without this the commit will be blocked from passing
  3. Then humans will review the code.  Regular users are usually able to +1 review.  Only those responsible for the repository can +2.
  4. Once +2 approved a check-mark will appear under the 'R' and the code will be merged into the central repository

Even after the changes on the central repository are approved, you will get notifications by email, you must pull (or sequentially fetch and merge) again before you and the central repository are in sync (yes even if the files happen to be the same on the 2 servers, the pointers are not in sync until you merge).  

IMPORTANT: READ THIS UNLESS GERRIT IS OLD HAT TO YOU

We are finding that many new to Gerrit are making serial commits.  When you do that without changing the pointer, the commits end up depending on each other in GIT (that is you keep building a local branch of your own).  When that happens if ANY fail then NONE of the commits along your local branch can be merged into source which is a waste of effort.  Unless the commits truly are dependent in code, it is better to reset your machine to the current head of the remote branch (merging in your changes) before making subsequent commits.  (Team -> Reset -> Remote Tracking -> <branch eg origin/master>)

When to commit locally and when to push remotely

Generally speaking you should commit locally for independent small units of work. So as an example if you are working on a feature, you may have incremental phases in completion of that feature. You should commit at each phase, the code should at least compile and run.

Generally speaking pushing remotely can be done for any commit. There is generally no need to bundle up multiple commits into one big push. The difference between a push and commit maybe more important if you're working offline as you can only push while online.

The reason for the above is because of the review model of gerrit. You don't want to do one big commit because it will be a nightmare to review and approve. Think about the example of converting 300 DBHandler calls into maybe 100 JPA objects. If that was 1 commit, it would take for ever to review and verify that commit. If you made 300 separate commits, the review process could at least proceed incrementally and in manageable size chunks. The push is for a similar reason, if you had 300 separate commits and you pushed all at once at the end of 6 months, there will be a sudden flood of 300 commits to review and it would be a huge backlog. If you pushed those 300 commits over a 6 month period, review of the commits could have started as soon as the first push was done.

Document Actions