How To Clone GitHub USEPA/VELMA to a Local Machine and Configure it for Eclipse Development

Overview

This guide explains how to get the VELMA source code from its GitHub repository via the TortoiseGit Git client/GUI, and how to set up Eclipse to work with it on a local machine.

Requirements

Before you begin, make sure you have the following available:

• A PC running Windows 10 connected to the internet.
• A valid GitHub account that is authorized to access the (private) USEPA/VELMA repository.
• The Git version control system installed on the PC.
• The TortoiseGit Git client installed on the PC.
• The Eclipse IDE installed on the PC.

Step-by-Step Instructions

1. Open Windows File Explorer and create a new Folder in an appropriate (for your needs) location.

Note that network drive locations may suffer a read/write performance lag.

2. Click into the newly-created folder, then right-click to open the folder's context menu.

Click-select the "Git Clone" menu item.
Example:

3. In the "Git clone - TortoiseGit" configuration dialog:

Set the "URL:" field to https://github.com/USEPA/VELMA.git
Set the "Directory:" field to the fully-qualified path of the new folder you created.
Click the "Recursive" check-box.
Click the "OK" button to begin cloning the VELMA source code from GitHub.
Example:

After you click OK, GitHub, via TortoiseGit askes for your username and password.
Enter the username for your GitHub account, and your password for that account.

Note: It's possible that this step may fail -- even if you enter a valid username and password combination.
In this case, TortoiseGit asks for your username and password again, with a slightly different dialog.
Keep trying: we've seen up two failed attempts followed by success on the third try.
We have no idea why TortoiseGit + GitHub behaves this way.

TortoiseGit will begin cloning the USEPA/VELMA repository into your local folder.
This can take a significant amount of time! A progress window should open and keep you informed of how the process is going.
Example:

Eventually, you should see the following concluding statement in the "Git clone" dialog:

4. Start Eclipse and Set the Workspace

Can't find Eclipse?
Click the Windows Start Menu icon, then type "Eclipse".
(There's no need to click into a text box -- just click the Start Menu icon and start typing.)
If it's properly installed, Eclipse should appear as a Search result. Click it to start it.
Example:

When Eclipse starts, it will either pop up a dialog asking you to "Select a directory as a workspace", or it will immediately open a workspace you have previously selected.
If the "Select a directory as a workspace" dialog appears, set the value of the "Workspace" entry to your new, local, cloned VELMA repository. Example: (Using the same location as previous examples)

Click the "Launch" button to select the directory as a workspace.
By default, Eclipse opens a new workspace with a "Welcome Tab" screen.

Click the Tab's [X] button to close it.
This should leave Eclipse displaying the "Java Browsing Perspective".
Notice the empty "Package Explorer" pane along the left side of the windows layout -- you will use that in the next step.

5. Import the VELMA source code into the Workspace

The Eclipse IDE won't automatically recognize that the various projects comprising VELMA already exist in the new workspace location that you've opened. To "import" them (i.e. make Eclipse aware of them), right-click inside the "Package Explorer" window pane, and click-select "Import" in the context menu.
Doing this should open the Import Select dialog. Expand the "General" item, click-select the "Existing Projects into Workspace" item, then click the "Next" button:

In the "Import Projects" dialog that opens next, fill in the "Select root directory" field with the full path of your workspace location.
Conveniently, if you click the "Browse" button, Eclipse opens a "Browse For Folder" sub-dialog that has your workspace location highlighted by default. You may have to scroll down in the folder browser to confirm this is so, but if it is, all you need to do is click the folder browser's OK button.
Once a root directory is set, the "Projects" list should fill with the names of the VELMA projects in your workspace.

Note that "PropertyViewer" is legacy and may be ignored: uncheck its checkbox, then click the "Finish" button.
Eclipse will "import" (i.e. become aware of) the already-existing VELMA projects, and they will be displayed in the "Package Explorer" window pane:

Notice the "[Velma_GitHub master]" nomenclature next to each project name: recent Eclipse versions have a Git client interface built in. If you are comfortable using it, you can perform Git actions through it, however, we strongly advise using TortoiseGit from Windows File Explorer windows unless you are already completely versed in Eclipse's Git client.

6. Set the Compiler compliance level for the projects in the VELMA Workspace

The VELMA simulator is intended to run with a Java 1.8 JRE (i.e. run under a 1.8 [J]ava [R]untime [E]nvironment).
This means that VELMA source code must be compiled to comply with version 1.8 Java.

Note: you can run VELMA source code for Java 1.8 on Java JREs newer than 1.8 -- VELMA only needs to be compiled for Java 1.8.

The Eclipse IDE can be configured to honor a specific "compiler compliance" level, but depending upon which version of Eclipse you have, the default level it is set for may differ from 1.8.
With Eclipse open to the workspace and VELMA source code projects you imported in the last step, click the "Window" menu, then click-select "Preferences":

In the "Preferences" dialog that opens next, click-expand the "Java" item in the preferences list, then click the "Compiler" sub-item:

Click the "Compiler compliance level:" drop-down list, and click-select "1.8".
Do the same for the "Generated .class files compatibility:" and "Source compatibility:" settings.

Note: some Eclipse IDE versions have the "Use default compliance settings" checkbox checked by default -- you may need to uncheck it in order to activate and set "Generated .class files compatibility:" and "Source compatibility:".

That's It!

You should be ready to work with the VELMA source code within your new Eclipse workspace.
(You may want to export your Eclipse preferences (e.g. editor fonts and syntax coloring) from your prior workspace, then import them into this new workspace.)