Obtaining and building Bio-Formats¶
Source code¶
The source code for this Bio-Formats release is available from the download page. 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:
- Select File ‣ Open Project from the menu - choose the top-level path to bioformats.git and click Open Project
- 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.
- Expand the ‘Modules’ folder to give a list of components and then double-click the desired project(s) to work with them.
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.
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.
Using Gradle, Maven or Ivy¶
All released .jar artifacts may be obtained through the OME Artifactory server. The “Client Settings” section of the Artifactory main page provides example code snippets for inclusion into your Gradle, Maven or Ivy project, which will enable the use of this repository.
Example snippets for using the Bio-Formats ${release.major}.${release.minor}-SNAPSHOT formats-gpl artifact are available for Gradle and for Maven. These may be copied into your project to enable the use of the Bio-Formats library components, and may be adjusted to use different components or different release or development versions of Bio-Formats.