.. _source-obtain-and-build: Obtaining and building Bio-Formats ================================== .. note:: Bio-Formats requires Java 8 or above .. _source-code: Source code ----------- The source code for this Bio-Formats release is available from the :downloads:`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 :program:`msysgit` or by editing :file:`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 :javadoc:`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 :sourcedir:`components ` folder, with some components further classified into :sourcedir:`components/forks `, depending on the nature of the project. See the :doc:`components` 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. .. _source-building: 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 :menuselection:`File --> Open Project` from the menu - choose the top-level path to bioformats.git and click :menuselection:`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. .. figure:: /images/netbeans.png :align: center :alt: Opening Bio-Formats in Netbeans Alternately, you can clone the source directly from NetBeans into a project by selecting :menuselection:`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 :file:`~/.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 :menuselection:`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 :command:`mvn eclipse:eclipse` to create the Eclipse project files, then use :menuselection:`File --> Import --> Existing Maven Projects`. IntelliJ IDEA ^^^^^^^^^^^^^ IntelliJ IDEA can build Bio-Formats using either Maven or Ant. Go to :menuselection:`File --> Open...` and browse to the top-level folder of your Bio-Formats working copy. Select :menuselection:`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 :file:`~/.m2/repository`. Simply run:: mvn With either Ant or Maven, you can use similar commands in any subproject folder to build just that component.