Skip to content

Developers guide

Jump to bottom Edit New page
gpihl edited this page Jun 19, 2017 · 8 revisions

How to get started as a developer (not an end-user)

Installation instructions

Below summary refers to Eclipse. Use of !NetBeans, etc. should be similar. The latest verified version is shown within brackets.

  1. Download and install Eclipse. * You probably want to set the default encoding to UTF-8 in Eclipse for both Eclipse -> Preferences -> General -> Workspace and all text content types under Eclipse -> Preferences -> General -> Content Types. * You probably want to show .resource files in Eclipse. This can be changed by pressing the small down-arrow in the Package Explorer, and then clicking "Filters...". * To run Eclipse smoothly, you probably want edit eclipse.ini to set the path to the VM and set decent memory allocation settings.
  2. Install recommended Eclipse plugins or corresponding required tools: * Java Development Tools, if not already in place [4.6.3]. * Maven Integration for Eclipse, m2eclipse [1.7.0].
  3. Go to the master branch of the jprime github page https://github.com/arvestad/jprime and click clone or download and copy the link to the jprime.git file.
  4. Open up a command line terminal and navigate to a suitable location and enter git clone https://github.com/arvestad/jprime.git
  5. You should create your own branch so that you do not modify the master branch of jprime, this can be done by entering git checkout -b [name_of_your_new_branch]
  6. Open up a new workspace in Eclipse and then select File -> Import -> Maven -> Existing Maven Project, now navigate to the directory where you cloned the git repo into where a Maven pom.xml file should be present, select it and click finish.
  7. If you want to be able to use git integration in Eclipse you can right click on jprime in the Package Explorer and select Team -> Share Project… -> Git -> jprime.git
  8. Make sure you set up Eclipse to use the same version of JDK as is specified by the Maven pom.xml file (currently 1.8 at the time of writing).
  9. Now everything should be set up and ready to go, you can right click jprime in the Package Explorer and do Run As -> Maven Install to build jprime, the compiled jprime JAR file should then end up in the target directory.

Builds

Builds are handled using the very competent (and alas complex) framework Maven. In particular, Maven takes care of all external dependencies (see also below). For creating releases, see Creating Releases.

File structure

The source file structure adheres to the Maven standard directory layout (as a subset thereof). Before adding new root folders, consider using a folder name proposed by this standard. Of particular importance are:

  • src/main/java - where main Java source code goes.
  • src/main/resources - where peripheral files for an actual release go.
  • src/main/python - where additional Python source code goes.
  • src/main/shellscript - where additional shellscript source code goes.
  • src/test/java - where Java unit tests and test suites go.
  • src/test/resources - where peripheral files for unit tests go.
  • target - where local builds are kept (not under version control).
  • lib - where non-Mavenized dependencies are kept, see below. Furthermore, non-Java resources kan be maintained in the same manner, e.g. src/main/shellscript and so forth.

Dependencies

Maven handles all external dependencies (most commonly JAR files). Typically, for a user, true Mavenized dependencies (and sub-dependencies!) are retrieved and stored under the ~/.m2 folder. When there is a need for a new dependency, do the following:

  1. Try searching for it using the interface shown for pom.xml in the source root. If it is found, just add it. Note that current builds (as opposed to proper releases) are often denoted SNAPSHOT.
  2. If it does not exist in an open Maven repository, one must use a workaround. Currently, this consists of adding the JAR file to the lib folder in the Git repository and then adding a system scope mock reference to the JAR in pom.xml (typically without aid of the interface).
  3. Try to add non-Javadoc dependencies. If you need Javadoc or sources, these can be collected without adding them as real project dependencies, e.g. in Eclipse by right clicking the project and selecting "Maven <- Download Javadoc".

Testing

Unit tests and test suites are handled with JUnit. Tests reside under the src/test/java folder in a package structure aligned with that of the source code. Maven can be told to run test suites when building by setting the boolean value [true\false] in the pom.xml file.

Bug tracking

Bug tracking is handled using the Issues page here at Github.

Logging

Logging is not handled with the built-in logger, but with Logback (included using Maven), which is a successor of log4j.

Application parameter parsing

Parameter parsing can be achieved in (almost) GNU style using JCommander (included using Maven).

XML

At the moment, ordinary XML tasks should be carried out with Java's built-in JAXB package if possible.

Bioinformatics

BioJava 4 (included using Maven) should be sufficient for common bioinformatics tasks involving alignments and similar.

Add a custom footer
Add a custom sidebar
Clone this wiki locally