Developer Basics

The instructions below provide basic guidance on how to set up command-line use of nshmp-haz.

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.

Required Software

• Java 7 JDK (or higher) for your system.
• Apache Ant
• Git. Git downloads are available here, however, most Linux and Mac OS systems come with Git already installed. Windows users may find it most convenient to install the GitHub Desktop application, which will also provide them with additional command line utilities.

Note for Windows users: If using Github Desktop, open the application. Under the 'wheel' menu (upper right), select 'Options...' and select 'Git Bash' as the default shell. This will make subsequent instructions consistent with those for other platforms.

Environment Variables

To build and run nshmp-haz from the command line, the JAVA_HOME, ANT_HOME, and PATH environment variables must be set. For example, on OS X with bash as the default shell, one might add the following to ~/.bash_profile:

export JAVA_HOME="$(/usr/libexec/java_home -v 1.7)"
export ANT_HOME=/usr/local/apache-ant-1.9.6
export PATH=$PATH:$ANT_HOME/bin

On a Linux system, this might look like:

export JAVA_HOME=/usr/lib/jvm/jdk1.7.0_45
export ANT_HOME=/usr/local/apache-ant-1.9.6
export PATH=$PATH:$ANT_HOME/bin

On Windows systems, environment variables are set through the System Properties > Advanced > Environemnt Variables... control panel. Depending on where Java and Ant are installed, the environment variable values might be:

JAVA_HOME     C:\Program Files\Java\jdk1.7.0_45
ANT_HOME      C:\Program Files\Java\apache-ant-1.9.6
Path          ... ;%ANT_HOME%/bin  (add to end of exisiting Path value)

Set Up Git

Follow the instructions on GitHub. If on Windows or Mac, it may be easier to use GitHub Desktop. 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.

For Developers (Optional)

Install Eclipse

The nshmp-haz repository is also configured as an Eclipse project. Eclipse is code development application, or integrated development environment (IDE). Eclipse provides automatic compilation, syntax highlighting, and integration with Git, among other useful features.

If you are interested in developing or modifying 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/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 approaches above are just a few of the ways to check out nshmp-haz. One can also navigate to nshmp-haz and select Clone in Desktop (right side). This will trigger a download via the GitHub Desktop application (or prompt you to install it if you haven't already).

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

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

Return to: Building & Running