Obtaining and building Bio-Formats

Note

Bio-Formats requires Java 8 or above

Source code

The source code for this Bio-Formats release is available from the downloads site. This release and the latest Bio-Formats source code are also available from the Git repository. This may be accessed using the repository path:

git@github.com:openmicroscopy/bioformats.git

More information about Git and client downloads are available from the Git project website. You can also browse the Bio-Formats source on GitHub

Note

Windows users must set git to use core.autocrlf=input to ensure that Bio-Formats uses LF rather than CRLF line endings, otherwise the build will fail (Genshi can’t process code templates with CRLF line endings, leading to broken sources being generated). This can be set globally in the registry when installing msysgit or by editing etc/gitconfig in the git installation directory. Annoyingly, these settings appear to override per-user and per-repository configuration values, requiring these to be set globally.

Lastly, you can browse the Bio-Formats Javadocs online, or generate them yourself using the “docs” Ant target.

Source code structure

The Bio-Formats code is divided into several projects. Core components are located in subfolders of the components folder, with some components further classified into components/forks, depending on the nature of the project. See the Component overview for more information, including associated build targets for each component.

Each project has a corresponding Maven POM file, which can be used to work with the project in your favorite IDE, or from the command line, once you have cloned the source.

Building from source

Instructions for several popular options follow. In all cases, make sure that the prerequisites are installed before you begin.

If you are interested in working on the Bio-Formats source code itself, you can load it into your favorite IDE, or develop with your favorite text editor.

NetBeans

NetBeans comes with Maven support built in. To import the Bio-Formats source, perform the following steps:

  1. Select File ‣ Open Project from the menu - choose the top-level path to bioformats.git and click Open Project
  2. In the ‘Projects’ tab on the left-hand side, expand the ‘Bio-Formats projects’ entry - you should now have a series of folders including ‘Other Sources’, ‘Modules’ and ‘Dependencies.
  3. Expand the ‘Modules’ folder to give a list of components and then double-click the desired project(s) to work with them.
Opening Bio-Formats in Netbeans

Alternately, you can clone the source directly from NetBeans into a project by selecting Team ‣ Git ‣ Clone Other… from the menu.

Eclipse

Eclipse uses the “Maven Integration for Eclipse” (m2e) plugin to work with Maven projects. It is more flexible than Eclipse’s built-in project management because m2e transparently converts between project dependencies and JAR dependencies (stored in the Maven repository in ~/.m2/repository) on the build path, depending on which projects are currently open.

We recommend using Eclipse 4.3 (Kepler) or later, specifically - “Eclipse IDE for Java developers”. It comes with m2e installed (http://eclipse.org/downloads/compare.php?release=kepler).

You can import the Bio-Formats source by choosing File ‣ Import ‣ Existing Maven Projects from the menu and browsing to the top-level folder of your Bio-Formats working copy. Alternatively, run the Eclipse Maven target with mvn eclipse:eclipse to create the Eclipse project files, then use File ‣ Import ‣ Existing Maven Projects.

IntelliJ IDEA

IntelliJ IDEA can build Bio-Formats using either Maven or Ant. Go to File ‣ Open… and browse to the top-level folder of your Bio-Formats working copy. Select Build ‣ Build Project or select the Maven tab on the right of the screen.

Command line

If you prefer developing code with a text editor such as vim or emacs, you can use the Ant or Maven command line tools to compile Bio-Formats. The Bio-Formats source tree provides parallel build systems for both Ant and Maven, so you can use either one to build the code.

For a list of Ant targets, run:

ant -p

In general, ant jars or ant tools is the correct command.

When using Maven, Bio-Formats is configured to run the “install” target by default, so all JARs will be copied into your local Maven repository in ~/.m2/repository. Simply run:

mvn

With either Ant or Maven, you can use similar commands in any subproject folder to build just that component.