Developer Basics

The instructions below provide basic, non-comprehensive, guidance on how to set up the tools to use and develop NSHMP codes: Java, Git, GitHub, and Eclipse.

What are Git and GitHub?

• Git is a distributed version control system. The 'distributed' means that you always work and version code locally (more).
• GitHub is a public hosting service that facilitates sharing and collaborative development of code and provides a home on the web for documentation and other project resources(more).
• Git repositories may be created anywhere on your system.
• Git repositories may be created locally and pushed to Github for sharing, or they may be created on GitHub and pulled down to your local system for editing.

Install Java 7

Download and install the Java 7 JDK (or higher) for your system. If you plan to build and run nshmp-haz from the command line, set a JAVA_HOME environment variable to point to the JDK directory. For instance, on OS X, this is usually something like:

/Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Contents/Home

and can be permanently set by adding:

export JAVA_HOME="$(/usr/libexec/java_home -v 1.7)"

to ones .bash_profile.

Set Up Git

Follow the instructions on GitHub. If on Windows or Mac, it may be easier to use the 'GitHub for Win/Mac' installer. This installs the components your system requires along with a helpful desktop application for managing communication between local repositories and GitHub. Launch the application and perform any configuration steps, using your GitHub username and email address.

Install Eclipse

Eclipse is code development application, or integrated development environment (IDE). Eclipse provides automatic compilation, syntax highlighting, and integration with Git, among other useful features.

The nshmp-haz repository is configured as an Eclipse project. If you are interested in developing or contributing to nshmp-haz, install the Eclipse IDE for Java developers. If you plan on developing and testing web-applications, install the Eclipse IDE for Java EE developers instead.

Use Eclipse to Check Out a Project

• Copy this url: https://github.com/pmpowers-usgs/nshmp-haz/.
• In Eclipse, select Window > Open Perspective > Other... > Git.
• In Eclipse, right-click in the Git Repositories tab and Paste repository path....
• Next. Next. Make sure the destination on your system is to your liking. Finish
• Right-click on the newly created repository entry and Import Projects....
• Ensure that Import exisiting projects is selected. Next. Finish.
• Now, Window > Open Perspective > Other... > Java.

There are many ways to view and interact with code in Eclipse. The Java Perspective should be set up with a Navigator on the left, a pane for Editors in the middle, and perhaps additional panels to the right and below the editor pane. All panels may be moved around via drag-n-drop. Other panels that are particularly helpful are Window > Show View > Other... Outline and Package Explorer (use the search box in the view selection dialog). It's an incredibly useful tool, but takes some getting used to.

For an alternate view of the project repository (a view that might be more helpful for non-Java projects), launch the GitHub application and File > Add a local repository.

Other Ways to Check Out a Project

The approach above is but one of a myriad of ways to get a project. One can also navigate to nshmp-haz and select Clone in Desktop (right side). This will trigger a download via your local GitHub application. The project could then be added to Eclipse by copying the local path of the repository and pasting as in the previous example.

The command line version of Git is also very convenient. Getting the project is as easy as:

git clone https://github.com/pmpowers-usgs/nshmp-haz.git

If you want to forego using Eclipse, an example script details how to compile the Java source.