Development

Developer guide

This page is a brief developers guide for the ga-worldwind-suite project. It describes general principles that should be adhered to by developers. Specifics on individual tools with the suite are given on tool-specific pages.

For information on getting started with the codebase, see this page.

Project structure

Each of the Java-based tools in the ga-worldwind-suite follow a common layout. This layout was chosen so that a future migration to Maven or similar will be relatively painless.

File/Folder	Description
src/main/java	The main application Java code for the tool
src/main/resources	Other application resources
src/experimental/java	Experimental application code *1
src/test/java	Java code for unit tests etc.
src/test/resources	Other resources for unit tests etc.
lib/build	Libraries used at compile time and/or by Eclipse
lib/package	Libraries packaged and released with the tool
lib/test	Libraries used when running unit tests etc.
lib/src	Library source code for use as reference within your IDE
target/classes	The output location for compiled classes
target/test-classes	The output location for compiled test classes
target/test-results	The output location for test results
target/test-reports	The output location for test reports
target/package	The output location for built JAR files
target/executable	The output location for the built tool distro
build.xml	The Ant build script for the tool
LICENSE-2.0.html	The Apache 2.0 license file
README.md	A readme file for the tool, marked up in Markdown.

\*1 Note that code from `src/main/experimental` source trees will eventually be moved into feature branches.

Git branches

The ga-worldwind-suite project uses a 3-tier branch structure. The diagram below represents the abstract heirarchy of branches in the project.

• Master - Represents the current stable release code for the project. It is tagged with important milestones (e.g. application releases etc.)

• Dev - The current development branch. Contains unreleased code.
  Once a stable release milestone has been released, a code freeze is put in place on Dev and changes are merged into Master and tagged.

• Feature and bugfix branches - These branches are used to implement specific features and/or bug fixes. Once completed and tested they are merged into Dev.
  Developers on long-running feature branches should regularly merge changes from Dev back into the feature branch. Feature and bugfix branches are named with the issue ID from the project issue tracker. Once a feature branch has been merged into Dev and the ticket closed, the branch is deleted to prevent a proliferation of branches.

In addition to these, developers may choose to create their own branches for contributing to features etc.

Building the tools

Each of the Java-based tools in the ga-worldwind-suite come with an Ant build script. This script contains targets for building, testing and packaging the tool. The default run target will execute the following build lifecycle:

build -> build-test -> test -> package -> [project specific tasks] -> executable

Lifecycle phase	Description
build	Compile application Java classes and copy resources
build-test	Compile test Java classes and copy resources
test	Execute unit tests and generate reports
package	Create the application JAR file
[project specific]	Perform project-specific tasks (e.g. sign JARs etc.)
executable	Create the application distro(s)

Notes:

• The test phases can be skipped by changing the variable perform_unit_tests in the project's Ant script.
• A clean is not performed during the default build lifecycle. This can be manually executed using the clean target.
• It is possible to execute the tools from within and IDE such as Eclipse without having to use the Ant build scripts. This allows faster testing turnaround and debugging etc.

Once complete, the default run target will have packaged an executable distro in the project's target/executable folder. The contents of this folder can be copied and distributed/installed as required.