4.2.1 OSCAR Development on Eclipse

Preface

There is no standard development environment.  After all you can develop OSCAR entirely at the command line with vi and git.   If you are using Mac or Windows you can use Sourcetree to clone the source but its not an IDE.  For those who develop on Linux or who don't want to use that proprietary tool you can continue with Eclipse to clone as below. 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
• v1.7 – Added Windows SSH note - Mar 16, 2017
• v1.7 – Preliminary information on bitbucket changes - March 20, 2017

Bitbucket

OSCAR EMR's code is hosted at bitbucket. If you were unable to attend the training, we have recorded the join.me session which can be found with the following link:

Navigate to bitbucket.org and create an account.  We will not replicate the bitbucket documentation here

You can access the bitbucket repository with https or ssh.

SSH Key (optional)

If you want to rock the command line you will need to install your key to bitbucket.  It also is a secure way that Eclipse can use, so we usually commend it.

If you already know or have SSH keys you can just provide it, otherwise for Linux do the following for your regular user : 

~$ 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 bitbucket user is compromised and the corresponding server key should be deleted, you'll need to 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.

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

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:
  

Create a new Working Branch

You will always start with a Jira Issue. Loginto Jira and create an issue, or if you move fast there might be a bug that hasn't been assigned and fixed yet ;-)

Then click the "create Branch" link on the Jira issue.  This will launch bitbucket where you can create a working branch for this issue.

Then select the correct project (usually OSCAR) and branch (usually stable for tested bug fixes) and check it out

 OSCAR is exampled above for other projects use the same pattern so for drugref use

eg https://bitbucket.org/oscaremr/drugref2/branch/DRUGREF-7-drugref-no-longer-updates-from

Cloning Oscar into Eclipse

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

Add the Clone...

The repository details

Note you can use either https: or ssh: using your bitbucket username and password

If you have already done this for previous work you should either delete your existing project if you want to start from fresh (although you could just change to the branching you want)

If you use ssh add the RSA key that the site will provide

Windows: If you get an error message and no list of Branches, you will probably have to add your private key. Use Windows, Preferences, General, Network Connections, SSH2 then add your private key to the list.

The Error Log is very well hidden.  Look in Help, About Eclipse, Installation Details, View Error Log. 

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

Select that one and deselect the others.
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

Its your private branch.  Make your changes and commit as you go.

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.

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) 

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

When your code works then you can create a Pull request for the code to be reviewed and merged into OSCAR