Build instructions for C++ bindings
===================================


This package provides language bindings for calling into the Bio-Formats Java
library from C++ in a cross-platform manner. As of this writing the bindings
are functional with GCC on Linux and Mac OS X systems, as well as with Visual
C++ 2005 and Visual C++ 2008 on Windows.

.. note::

    The JACE C++ bindings require Java 6 or Java 7 to build and run.
    They do *not* currently work with Java 8.

Compile-time dependencies
-------------------------

To build the Bio-Formats C++ bindings from source, the following modules are 
required:

- `Apache Maven <http://maven.apache.org/>`_
    Maven is a software project management and comprehension tool. Along with
    Ant, it is one of the supported build systems for the Bio-Formats Java
    library, and is used to generate the Bio-Formats C++ bindings.

- `CMake <http://www.cmake.org/>`_
    CMake is a cross-platform, open source build system generator, commonly 
    used to build C++ projects in a platform-independent manner. CMake 
    supports GNU make as well as Microsoft Visual Studio, allowing the 
    Bio-Formats C++ bindings to be compiled on Windows, Mac OS X, Linux and  
    potentially other platforms.

- `Boost Thread <http://www.boost.org/>`_
    Boost is a project providing open source portable C++ source libraries. It 
    has become a suite of de facto standard libraries for C++. The Bio-Formats  
    C++ bindings require the Boost Thread module in order to handle C++ 
    threads in a platform independent way.

- `Java Development Kit <http://www.oracle.com/technetwork/java/javase/downloads/>`_
    Version 6 or 7 is required; version 8 is not currently supported.
    At runtime, only the Java Runtime Environment (JRE) is necessary
    to execute the Bio-Formats code. However, the full J2SE
    development kit is required at compile time on some platforms
    (Windows in particular), since it comes bundled with the |JVM|
    shared library (jvm.lib) necessary to link with Java.

For information on installing these dependencies, refer to the page for your
specific platform: 
:doc:`Windows <build-windows>`,
:doc:`Mac OS X <build-macosx>`,
:doc:`Linux <build-linux>`.

How to build
------------

The process of building the Bio-Formats C++ bindings is divided into two 
steps:

1) Generate a C++ project consisting of "proxies" which wrap the Java code.
   This step utilizes the Maven project management tool, specifically a
   Maven plugin called cppwrap.

2) Compile this generated C++ project. This step utilizes the cross-platform
   CMake build system.

For details on executing these build steps, refer to the page for your
specific platform: 
:doc:`Windows <build-windows>`,
:doc:`Mac OS X <build-macosx>`,
:doc:`Linux <build-linux>`.

Build results
-------------

If all goes well, the build system will:

1) Generate the Bio-Formats C++ proxy classes;
2) Build the Jace C++ library;
3) Build the Java Tools C++ library;
4) Build the Bio-Formats C++ shared library;
5) Build the showinf and minimum_writer command line tools,
   for testing the functionality.

Please be patient, as the build may require several minutes to complete.

Afterwards, the dist/formats-bsd subdirectory will contain the following files:

1) libjace.so / libjace.jnilib / jace.dll :
     Jace shared library

2) libformats-bsd.so / libformats-bsd.dylib / formats-bsd.dll :
     C++ shared library for BSD-licensed readers and writers

3) jace-runtime.jar :
     Jace Java classes needed at runtime

4) bioformats_package.jar :
     Bio-Formats Java library needed at runtime

5) libjtools.so / libjtools.jnilib / jtools.dll :
     Java Tools shared library

6) showinf / showinf.exe :
     Example command line application

7) minimum_writer / minimum_writer.exe :
     Example command line application

Items 1-4 are necessary and required to deploy Bio-Formats with your C++
application. Item 5 (jtools) is a useful helper library for managing the Java
virtual machine from C++, but is not strictly necessary to use Bio-Formats.
All other files, including the example programs and various build files
generated by CMake, are not needed.

If you prefer, instead of using the bioformats_package.jar bundle, you can provide
individual JAR files as appropriate for your application. For details, see 
:doc:`using Bio-Formats as a Java library <../java-library>`.

Please direct any questions to the OME team on the 
:forum:`forums <>` or :mailinglist:`mailing lists <>`.