OSCAR Development on Eclipse

This is a walkthrough on how to develop for OSCAR on Eclipse.

Preface

There is no standard development environment.  After all you can develop OSCAR entirely at the command line with vi and git.  For a project of this scope an IDE makes it that much easier. These basic instructions are adequate for developing Oscar on Eclipse.  You can install Eclipse on any modern OS, but we encourage the better Open Source ones.  

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 – Revised for Eclipse version 4.4 Luna, initial release – Dec 10, 2014
• v1.6 – Revised for Eclipse version 4.6.2 Neon – Jan 3, 2017

The document is based on older instructions for OSCAR 12 and is copyright © 2011-17 by Peter Hutten-Czapski under the Creative Commons Attribution-Share Alike 3.0 Unported License

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.  Just navigate to (http://bitbucket.org/oscaremr).  

Create an account using the same email as your JIRA account. Send an email to Marc Dumontier (marc.dumontier@oscar-emr.com) to request developer access to the team. In the mean time, upload your SSH key under your "Bitbucket Settings".

- For "SSH Keys" : 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 bitbucket administrator and or login to the bitbucket 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.

Click add and it should list it as an added key on the 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 

The latest eclipse can be obtained directly from their official site at the downloads section

http://www.eclipse.org/downloads/index.php

now you will see the latest versions available

when this was written it was eclipse neon (Jan 2017)

if you go to the above link from linux then you will be presented with the linux versions by default. if you go to the website within other OS, make sure you select the right platform.

then download the right choice for you ( for me its eclipse IDE for Java EE)

you can select any mirror you like (I downloaded from the main site in Canada)

after downloading

you will see a archive named like eclipse-inst-linux64.tar.gz

1. extract installer

tar xf eclipse-inst-linux64.tar.gz

2. change to the extraction directory

cd eclipse-installer

3. run the installer as regular user (unless you want to install it in /opt/eclipse when you must invoke the installer with sudo)

./eclipse-inst

4. Install the version you want into your home directory. it's in the directory /home/user/eclipse-version/eclipse

To run eclipse from the install directory

go to the directory /home/user/eclipse/java-neon

and double click the file "eclipse" and that's it.

alternately add it to the desktop menu with a file called /usr/share/applications/eclipse-neon.desktop

with the following content (replace peter in the paths below with the appropriate user)

[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Name=Eclipse IDE
Comment=Eclipse Integrated Development Environment
Icon=/home/peter/eclipse/java-neon/eclipse/icon.xpm
Exec=/home/peter/eclipse/java-neon/eclipse/eclipse
NoDisplay=false
Categories=Development;IDE;
Name[en]=Eclipse
Terminal=false

Configuring the Git 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:

Cloning Oscar into Eclipse

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

Add the Clone...

The repository details should be provided for your bitbucket 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.

Add the RSA key that the site will provide

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

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

Then you will be asked for a secure password if you left the checkbox "store in a secure store" earlier (not suggested or shown)

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

Almost there

[Next >] will determine how to share the imported project.  Select oscar and Finish.

Identify the imported project by clicking on the checkbox

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

and here you have it, 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

HINT: If you have never used the Eclipse/Gerrit/Git combination you are STRONGLY suggested to load the test repository. 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.

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 mergeable 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.

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 committed" at the same time. Now when you commit, it's committed locally. This means no one else except you has these changes still.

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.

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

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

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).

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.

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

Next Steps

Unless Gerrit is old hat to you, most experienced programmers make several errors that prevent their code from being in a condition to be reviewed, or to successfully merge into OSCAR.  Read the tips section.

 copyright © 2012-2017 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License ^©