Getting Started with OpenSHA Development

Obtaining Source Code

Three options are available to obtain the OpenSHA source code:

1. Browse Source on this website. Once in the trunk folder, the current release code may be downloaded as a zip file (the link is at the bottom of the page).

2. Check the codebase out directly from our Subversion (SVN) repository. We recommend using a newer version of the ​SVN client, even if your computer already has a client installed. Navigate to the directory you wish to download the project to, and run (substituting your username and password as appropriate:

svn checkout --username <username> --password <password> http://intensity.usc.edu/svn/opensha/trunk
}}}[[BR]][[BR]]

----
 3. Check the codebase out from our Subversion (SVN) repository using Eclipse.

== Obtaining Source Code via Eclipse ==

If you plan on working with OpenSHA, an alternative, and perhaps easier approach is to download the code from within Eclipse:

=== 1) Download Eclipse ===

The latest version of Eclipse can be obtained from [http://www.eclipse.org/downloads/ The Eclipse Website]

The "Eclipse IDE for Java Developers" should be fine, however the Enterprise Edition (EE) will work as well.[[BR]][[BR]]

=== 2) Install the Subversion (SVN) Plug-in ===

The Eclipse SVN Plug in is called "Subclipse".

To install in Eclipse, follow the tutorial here: [http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA Subclipse Installation]

(be sure to use `http://subclipse.tigris.org/update_1.6.x` as the update site when prompted)[[BR]][[BR]]

=== 3) Add the OpenSHA Source Repository ===

Once Subclipse is properly installed, from within eclipse:
 * Select ''`Window > Open Perspective > Other`''.
 * Select ''`SVN Repository Exploring`'' and hit ''`OK`''.

The ''`SVN Repository`'' tab should now be visible:
 * Click the ''`Add SVN Repository`'' button shown here...
[[Image(http://intensity.usc.edu/trac/opensha/attachment/wiki/SettingUpEclipse/svn_add_repo_button.png?format=raw)]]

 * Enter `http://intensity.usc.edu/svn/opensha` as the ''`URL`'' and hit ''`Finish`''.
 * Enter your ''`username`'' and ''`password`''.[[BR]][[BR]]

=== 4) Check out the OpenSHA Project ===

 * Click the arrow to expand the repository tree.
 * Right click on ''`trunk`'' and select ''`Checkout...`''
[[Image(http://intensity.usc.edu/trac/opensha/attachment/wiki/SettingUpEclipse/svn_checkout.png?format=raw)]]

 * If you are happy with the default options (they are fine for most people), just click ''`Finish`''.
     * To specify where to put your "Working Copy" of the project, click ''`Next`'' instead.
 * Be patient, it may take a little while to check out the entire project the first time.
 * Once it is checked out, switch to the Java perspective  ''`Window > Open Perspective > Java`'' (or ''`Other`'', then ''`Java`'').
 * More patience; it will probably take a little while to build the project as well (you should see ''`Building Workspace`'' in the lower right corner of the Eclipse window.[[BR]][[BR]]

----
== Working with OpenSHA ==

The instructions above will enable any registered user to get a copy of the ''`trunk`'' or current codebase. Any new code by authorized developers, however, must be committed to the repository on a ''`branch`''. The details of merging and branching are outlined in [http://svnbook.red-bean.com/ The SVN Book] and we encourage everyone involved to keep it handy. Some very basic instructions and guidelines are provided below.[[BR]][[BR]]

=== Branching ===
OpenSHA development occurs on branches. To create a branch:

 * Switch to the ''`SVN Repository Exploring`'' perspective (see Step 3 above).
 * Right click on ''`trunk`'' and select ''`Branch/Tag...`''
[[Image(http://intensity.usc.edu/trac/opensha/attachment/wiki/SettingUpEclipse/svn_branch.png?format=raw)]]

 * In the window that follows, enter the following address in the ''`Copy to URL`'' field, replacing ''`username`'' and ''`branchname`'' as appropriate:
{{{
  http://intensity.usc.edu/svn/opensha/branches/username_branchname
}}}
 * Click ''`Finish`'' (or ''`Next`'' for more advanced options).
 * Once the branch is created, expand the ''`branches`'' folder and check out ''`username_branchname`'' as a "Working Copy" using ''`Checkout...`'' (see Step 4 above).[[BR]][[BR]]

=== Merging ===

When new code is ready for inclusion in a release, project admins will assist with any required updates to a developers branched code and with merging it into the main line of the project. 

[[BR]][[BR]][[BR]]