OME-Files C++ overview
======================
OME-Files is a native C++ implementation of the Java Bio-Formats
interfaces, providing a reference implementation of the OME-TIFF file
format and the OME-XML metadata model for C++ developers.
Unlike the JACE bindings, this does not wrap the Java implementation.
Readers and writers are provided for TIFF and OME-TIFF. All other
readers and writers from the Bio-Formats Java implementation are
currently unavailable.
.. note::
Due to the renaming of Bio-Formats to OME-Files, this will result in
an API break between version 5.1 and 5.2 as a result of the renamed
namespaces. Further breaking changes are planned as the basic
interfaces are cleaned up to make them more flexible and efficient.
Prebuilt packages
-----------------
MacOS X Homebrew
^^^^^^^^^^^^^^^^
Run::
brew tap homebrew/science
brew install bioformats-cpp [--without-docs] [--with-qt5]
.. option:: --without-docs
Do not build the HTML version of this manual (built by default).
.. option:: --with-qt5
Build the Qt5 OpenGL viewer widget library :file:`ome-qtwidgets`
and :file:`ome-files view` image viewer (not built by default).
Prerequisites
-------------
In order to build the C++ library and its documentation, a number of
packages are required to be installed. Note that the minimum version
is the minimum version we regularly test with; older versions may work
but are not supported. Some packages are required only for building
OME-Files (*OF [super]build*). A subset of these are required for
building client applications making use of OME-Files (*Client
build*). For end-user deployment (*Deploy*), the library packages
rather than the development packages should be preferred; in some
cases such as for Boost and Qt5, these are split up into a separate
package for each library.
OME-Files may be built in two ways. The first is “standalone†(*OF
build*) and requires the prerequisites to be installed in advance, for
example using your operating system's package manager. The second is
using a “super-build†(*OF superbuild*) which builds the prerequisites
in addition to OME-Files, and is useful on systems where the
prerequisites are unavailable, for example on Windows which lacks a
package manager or on older systems such as CentOS 6 where the
versions available through a package manager are too old. Note that
the super-build cannot provide *all* prerequisites; some will still
need installing before building, shown in the table below. Also note
that the super-build may link against some system libraries when
building packages such as libtiff, where the build system for the
package will optionally use certain system libraries if available;
this may result in a build which will not work on other systems unless
these libraries are also installed. In the future, these dependencies
will also be provided by the super-build.
.. tabularcolumns:: |l|l|l|c|c|c|c|
+---------------+--------------+--------------+--------------------------------------------------+
| | Version | When required |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Package | Recommended | Minimum | OF build | OF superbuild | Client build | Deploy |
+===============+==============+==============+==========+===============+==============+========+
| Boost | 1.54 | 1.48 | \• | | \• | \• |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| HDF5 | 1.8.x | 1.8.x | â—¦ | | â—¦ | â—¦ |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| PNG | 1.2 | 1.2 | \• | | \• | \• |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| TIFF | 4.0.3 | 3.9.5 | \• | | \• | \• |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Xerces-C | 3.0 | 3.0 | \• | | \• | \• |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| GLM | 0.9.6 | 0.9.5 | \* | \* | \* | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Qt5 | 5.2 | 5.0 | \* | \* | \* | \* |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| CMake | 3.4 | 3.2 | \• | \• | | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Python | 2.7 | 2.6 | \• | \• | | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Python Genshi | 0.7 | 0.6 | \• | \• | | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Git | 2.1.x | 1.7.x | â—¦ | â—¦ | | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| GTest | 1.7 | 1.5 | â—¦ | â—¦ | | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Doxygen | 1.8 | 1.6 | †| †| | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Graphviz | 2.x | 1.8.10 | †| †| | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| Python Sphinx | 1.2.x | 1.1.x | ठ| ठ| | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
| TeX (XeLaTeX) | TeXLive 2015 | TeXLive 2012 | § | § | | |
+---------------+--------------+--------------+----------+---------------+--------------+--------+
\•
Required for OME-Files build; headers may be needed for client
build; libraries and any data files required for deployment
â—¦
Optional for OME-Files build; if used for the OME-Files build,
headers may be required for client build and libraries and any data
files required for deployment
\*
Optional, needed to build the OpenGL image viewer and client applications
â€
Optional, needed to build the API reference
‡
Optional, needed to build the manual pages
§
Optional, needed to build the manual (HTML and PDF)
Quick start
^^^^^^^^^^^
Install the following packages to build OME-Files C++. A subset of
these packages (or their dependencies) may be used for deployment,
where the development package headers and tools for building
documentation etc. are not required. Run the appropriate command below
for your platform to install the build dependencies:
BSD Ports
``pkg install devel/boost-all devel/cmake science/hdf5 graphics/png lang/python textproc/py-genshi graphics/tiff textproc/xerces-c3 devel/git devel/googletest math/glm devel/qt5 graphics/graphviz devel/apache-ant java/openjdk7 textproc/py-sphinx print/texlive-full``
Debian/Ubuntu
``apt-get install build-essential libboost-all-dev cmake libhdf5-dev libpng12-dev python python-genshi libtiff5-dev libxerces-c-dev git libgtest-dev libglm-dev qt5-default libqt5-opengl5-dev libqt5-svg5-dev graphviz ant ant-contrib ant-optional openjdk-7-jdk openjdk-7-jre python-sphinx texlive-full``
Partial quick starts
^^^^^^^^^^^^^^^^^^^^
Homebrew and RedHat/CentOS do not provide packages for everything that is
needed. The commands listed will install *most* of the dependencies, but
further dependencies will need to be installed as described in various
sections below.
Homebrew
``brew install boost cmake hdf5 libpng python libtiff xerces-c git glm qt5 graphviz ant``
RedHat/CentOS
``yum install libhdf5-devel libpng-devel python python-genshi libtiff-devel xerces-c-devel git gtest-devel graphviz java-1.7.0-openjdk``
See the :ref:`boost_req` section for installing a newer version of Boost.
Basic toolchain
^^^^^^^^^^^^^^^
A functional compiler, assembler and linker are required to build C++
code.
If possible, install the following packages:
+------------------+-----------------+
| System | Package |
+==================+=================+
| BSD Ports | N/A* |
+------------------+-----------------+
| Debian/Ubuntu | build-essential |
+------------------+-----------------+
| Homebrew | N/A†|
+------------------+-----------------+
| RedHat/CentOS | N/A‡ |
+------------------+-----------------+
| Windows | N/A§ |
+------------------+-----------------+
\*
Available by default
â€
Install :program:`Xcode`
‡
Run ``yum groupinstall "Development Tools"``
§
Install Visual Studio or `Visual Studio Express <http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop>`__
.. _boost_req:
Boost
^^^^^
If possible, install one of the following packages:
+------------------+------------------+
| System | Package |
+==================+==================+
| BSD Ports | devel/boost-all |
+------------------+------------------+
| Debian/Ubuntu | libboost-all-dev |
+------------------+------------------+
| Homebrew | boost |
+------------------+------------------+
| RedHat/CentOS | boost-devel |
+------------------+------------------+
1.48 or later needed for Boost.Geometry; 1.54 or later needed for
Boost.Geometry spatial indexes. RHEL/CentOS 6 users might want to
look at the `Boost 1.48 SCL
<https://www.softwarecollections.org/en/scls/denisarnaud/boost148/>`_
or build a more recent Boost release.
CMake
^^^^^
If possible, install the following packages:
+------------------+-------------+
| System | Package |
+==================+=============+
| BSD Ports | devel/cmake |
+------------------+-------------+
| Debian/Ubuntu | cmake |
+------------------+-------------+
| Homebrew | cmake |
+------------------+-------------+
| RedHat/CentOS | cmake |
+------------------+-------------+
- `Website <http://cmake.org/>`__
- `Download <http://cmake.org/cmake/resources/software.html>`__
HDF5
^^^^
If possible, install the following packages:
+------------------+---------------+
| System | Package |
+==================+===============+
| BSD Ports | science/hdf5 |
+------------------+---------------+
| Debian/Ubuntu | libhdf5-dev |
+------------------+---------------+
| Homebrew | hdf5 |
+------------------+---------------+
| RedHat/CentOS | libhdf5-devel |
+------------------+---------------+
PNG
^^^
If possible, install the following packages:
+------------------+--------------+
| System | Package |
+==================+==============+
| BSD Ports | graphics/png |
+------------------+--------------+
| Debian/Ubuntu | libpng12-dev |
+------------------+--------------+
| Homebrew | libpng |
+------------------+--------------+
| RedHat/CentOS | libpng-devel |
+------------------+--------------+
Python
^^^^^^
If possible, install the following packages:
+------------------+-------------+
| System | Package |
+==================+=============+
| BSD Ports | lang/python |
+------------------+-------------+
| Debian/Ubuntu | python |
+------------------+-------------+
| Homebrew | python |
+------------------+-------------+
| RedHat/CentOS | python |
+------------------+-------------+
- `Website <https://www.python.org/>`__
- `Download <https://www.python.org/download/releases/2.7.8/>`__
- `Extra packages for Windows <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`__
For Python on Windows, either download separate installers for each
package, or install ``setuptools`` and ``pip`` for Python, then ``pip
install`` needed packages; ensure downloaded packages are 64-bit if
using 64-bit Python.
Python Genshi
^^^^^^^^^^^^^
If possible, install the following packages:
+------------------+--------------------+
| System | Package |
+==================+====================+
| BSD Ports | textproc/py-genshi |
+------------------+--------------------+
| Debian/Ubuntu | python-genshi |
+------------------+--------------------+
| Homebrew | N/A |
+------------------+--------------------+
| RedHat/CentOS | python-genshi |
+------------------+--------------------+
Use ``pip install genshi`` if a packaged version is not available.
TIFF
^^^^
If possible, install the following packages:
+------------------+----------------+
| System | Package |
+==================+================+
| BSD Ports | graphics/tiff |
+------------------+----------------+
| Debian/Ubuntu | libtiff5-dev* |
+------------------+----------------+
| Homebrew | libtiff |
+------------------+----------------+
| RedHat/CentOS | libtiff-devel |
+------------------+----------------+
\*
libtiff4-dev with older releases
4.0.2 and earlier do not have TIFFField accessor functions.
Xerces-C
^^^^^^^^
If possible, install the following packages:
+------------------+--------------------+
| System | Package |
+==================+====================+
| BSD Ports | textproc/xerces-c3 |
+------------------+--------------------+
| Debian/Ubuntu | libxerces-c-dev |
+------------------+--------------------+
| Homebrew | xerces-c |
+------------------+--------------------+
| RedHat/CentOS | xerces-c-devel |
+------------------+--------------------+
Git
^^^
If possible, install the following packages:
+------------------+--------------+
| System | Package |
+==================+==============+
| BSD Ports | devel/git |
+------------------+--------------+
| Debian/Ubuntu | git |
+------------------+--------------+
| Homebrew | git |
+------------------+--------------+
| RedHat/CentOS | git |
+------------------+--------------+
- `Website <http://www.git-scm.com/>`__
- `Download <http://www.git-scm.com/downloads>`__
Google Test (gtest)
^^^^^^^^^^^^^^^^^^^
If possible, install the following packages:
+------------------+------------------+
| System | Package |
+==================+==================+
| BSD Ports | devel/googletest |
+------------------+------------------+
| Debian/Ubuntu | libgtest-dev |
+------------------+------------------+
| Homebrew | N/A* |
+------------------+------------------+
| RedHat/CentOS | gtest-devel |
+------------------+------------------+
\*
`gtest is not available in homebrew <http://answers.ros.org/question/42335/mac-os-x-install-error-no-available-formula-for-gtest/>`__
If using an GTest, make sure that :envvar:`GTEST_ROOT` is set
in the environment, or that ``-DGTEST_ROOT=/path/to/gtest`` is passed
to :program:`cmake` and that this points to the location where the
:program:`gtest` library was installed. If the library is located on
the default library search path, this is not necessary.
- `Website <https://code.google.com/p/googletest/>`__
- `Zip download <https://code.google.com/p/googletest/downloads/detail?name=gtest-1.7.0.zip>`__
- `SVN tag <http://googletest.googlecode.com/svn/tags/release-1.7.0>`__
GLM
^^^
If possible, install the following packages:
+------------------+--------------+
| System | Package |
+==================+==============+
| BSD Ports | math/glm |
+------------------+--------------+
| Debian/Ubuntu | libglm-dev |
+------------------+--------------+
| Homebrew | glm |
+------------------+--------------+
| RedHat/CentOS | N/A |
+------------------+--------------+
.. note::
Older versions will allow compilation but use degrees rather than
radians, which will lead to unexpected results.
- `Website <http://glm.g-truc.net/0.9.6/index.html>`__
- `Download <http://sourceforge.net/projects/ogl-math/files/>`__
Qt5
^^^
If possible, install the following packages:
+------------------+------------------------------------------------+
| System | Package |
+==================+================================================+
| BSD Ports | devel/qt5 |
+------------------+------------------------------------------------+
| Debian/Ubuntu | qt5-default libqt5-opengl5-dev libqt5-svg5-dev |
+------------------+------------------------------------------------+
| Homebrew | qt5* |
+------------------+------------------------------------------------+
| RedHat/CentOS | N/A |
+------------------+------------------------------------------------+
\*
Add :file:`/usr/local/opt/qt5/bin` to :envvar:`PATH`
- `Website <http://www.qt.io/>`__
- `Download <http://www.qt.io/download/>`__
Doxygen
^^^^^^^
+------------------+---------------+
| System | Package |
+==================+===============+
| BSD Ports | devel/doxygen |
+------------------+---------------+
| Debian/Ubuntu | doxygen |
+------------------+---------------+
| Homebrew | doxygen |
+------------------+---------------+
| RedHat/CentOS | doxygen |
+------------------+---------------+
- `Website <http://www.stack.nl/~dimitri/doxygen/>`__
- `Download <http://www.stack.nl/~dimitri/doxygen/download.html>`__
Graphviz
^^^^^^^^
If possible, install the following packages:
+------------------+-------------------+
| System | Package |
+==================+===================+
| BSD Ports | graphics/graphviz |
+------------------+-------------------+
| Debian/Ubuntu | graphviz |
+------------------+-------------------+
| Homebrew | graphviz |
+------------------+-------------------+
| RedHat/CentOS | graphviz |
+------------------+-------------------+
- `Website <http://graphviz.org/>`__
- `Download (for Windows) <http://graphviz.org/Download_windows.php>`__
Apache Ant
^^^^^^^^^^
If possible, install one of the following packages:
+------------------+------------------------------+
| System | Package |
+==================+==============================+
| BSD Ports | devel/apache-ant |
+------------------+------------------------------+
| Debian/Ubuntu | ant ant-contrib ant-optional |
+------------------+------------------------------+
| Homebrew | ant |
+------------------+------------------------------+
| RedHat/CentOS | N/A |
+------------------+------------------------------+
- `Website <http://ant.apache.org/>`__
- `Download <http://ant.apache.org/bindownload.cgi>`__
Java
^^^^
If possible, install one of the following packages:
+------------------+-----------------------------+
| System | Package |
+==================+=============================+
| BSD Ports | java/openjdk7 |
+------------------+-----------------------------+
| Debian/Ubuntu | openjdk-7-jdk openjdk-7-jre |
+------------------+-----------------------------+
| Homebrew | N/A |
+------------------+-----------------------------+
| RedHat/CentOS | java-1.7.0-openjdk |
+------------------+-----------------------------+
- `Download <http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html>`__
Python Sphinx
^^^^^^^^^^^^^
If possible, install the following packages:
+------------------+--------------------+
| System | Package |
+==================+====================+
| BSD Ports | textproc/py-sphinx |
+------------------+--------------------+
| Debian/Ubuntu | python-sphinx |
+------------------+--------------------+
| Homebrew | N/A (use pip) |
+------------------+--------------------+
| RedHat/CentOS | N/A (use pip) |
+------------------+--------------------+
Use ``pip install sphinx`` if a packaged version is not available.
TeX
^^^
If possible, install the following packages:
+------------------+--------------------+
| System | Package |
+==================+====================+
| BSD Ports | print/texlive-full |
+------------------+--------------------+
| Debian/Ubuntu | texlive-full |
+------------------+--------------------+
| Homebrew | N/A* |
+------------------+--------------------+
| RedHat/CentOS | N/A†|
+------------------+--------------------+
\*
Install TeXLive or MacTeX
â€
Provides an obsolete version; install TeXLive
- `TeXLive website (for Unix) <https://www.tug.org/texlive/>`__
- `TeXLive quick install (for Unix) <https://www.tug.org/texlive/quickinstall.html>`__
- `MacTeX website (for MacOS X) <https://tug.org/mactex/>`__
- `MacTeX download (for MacOS X) <http://mirror.ctan.org/systems/mac/mactex/MacTeX.pkg>`__
- `MikTeX website (for Windows) <http://www.miktex.org/>`__
- `MikTeX download (for Windows) <http://www.miktex.org/download>`__
Local font configuration may be required to make the
TeX Gyre fonts available:
- Linux and FreeBSD: Use the provided :program:`fontconfig` template
or create your own
- MacOS X: Add to system using :program:`FontBook`
- Windows: May need adding to the system fonts if not found
automatically
Sources
-------
Download the OME-Files source code or the CMake superbuild source
code, depending upon which type of build is required, as described
above. The :downloads_cpp:`downloads page <>` provides links to the
source releases for both, as well as links to their git repositories.
If you wish to build a specific release of OME-Files, the source
release is appropriate, but if you wish to build the latest
development work, or make changes to the sources, the git repository
will be more useful.
Build environment
-----------------
General
^^^^^^^
Custom configuration is needed primarily on Windows, where the needed
tools may not be on the search path by default. There are several
possible approaches here:
- Add to the system environment (globally)
- Add to the user environment (affects a single user)
- Set in a batch file and run this to set up the environment on demand
(local to the command shell)
The first will affect all programs running on the system and so may
cause problems, particularly if multiple configurations or tool
versions are to be used. The last offers the greatest flexibility and
safety, and can be sourced automatically when starting a shell if a
console replacement such as :program:`ConsoleZ` is used.
- Activate a python virtualenv if needed
- Ensure that needed tools are on the user :envvar:`PATH`
(e.g. :program:`ant`, :program:`cmake`, :program:`doxygen`,
:program:`dot`, :program:`git`, :program:`python`, :program:`java`,
:program:`sphinx`, :program:`xelatex`)
- Set ``CMAKE_PREFIX_PATH`` if some libraries and tools are not on the
default search path. Not all tools need to be on the default path;
some will be discovered automatically by :program:`cmake`
Homebrew
^^^^^^^^
If ``qt5`` and ``glm`` are installed, for building the Qt image
viewer, ensure that :file:`/usr/local/opt/qt5/bin` is on the
:envvar:`PATH` to allow Qt to be autodetected by :program:`cmake`.
Configuring
-----------
OME-Files uses :program:`cmake`, a generic cross-platform build
system which generates build files for a large number of common build
systems and IDEs. For example, on BSD, Linux and MacOS X, Unix
:program:`make` :file:`Makefile` files may be created. On Windows,
Visual Studio :program:`msbuild` :file:`.sln` solution files and
:file:`.vcxproj` project may be created. However, Eclipse, Sublime
Text or several other IDEs or alternative build systems may be used
instead, if desired.
Start by creating a temporary build directory. This directory may be
in any location inside or outside the OME-Files source tree.
However, the source directory cannot be used as the build directory.
(This fills the source tree full of autogenerated files.)
Run :program:`cmake` from the temporary build directory::
% mkdir build
% cd build
% cmake [-G <generator>] [<options>] /path/to/source
Where ``<generator>`` is the platform-specific build system to
generate files for, and ``<options>`` are any additional options to
configure the build to your requirements. See below for information
about the different generators.
Run ``cmake -LH`` to see the configurable project options; use
``-LAH`` to see advanced options. The following basic options are
supported:
cxxstd-autodetect=(ON|OFF)
Enable or disable (default) C++ compiler standard autodetection. If
enabled, the compiler will be put into C++11 mode if available,
otherwise falling back to C++03 or C++98. If disabled, the default
compiler standard mode is used, and it is the responsibility of the
user to add the appropriate compiler options to build using the
required standard. This is useful if autodetection fails or a
compiler is buggy in certain modes (e.g. GCC 4.4 or 4.6 require
``-std=gnu++98`` or else ``stdarg`` support is broken).
doxygen=(ON|OFF)
Enable doxygen documentation. These will be enabled by default if
doxygen is found.
extended-tests=(ON|OFF)
Some of the unit tests are comprehensive and run many thousands of
tests. These are enabled by default, but by setting to OFF a
representative subset of the tests will be run instead to save time.
extra-warnings=(ON|OFF)
Enable or disable additional compiler warnings in addition to the
default set. These are disabled by default since they trigger a large
number of false positives, particularly in third-party libraries
outside our control.
fatal-warnings=(ON|OFF)
Make compiler warnings into fatal errors. This is disabled by
default.
qtgui=(ON|OFF)
Enable building of the Qt5 widget library ome-qtwidgets and a simple
Qt5 OpenGL image viewer. This is enabled by default if the needed
libraries are available.
relocatable-install=(ON|OFF)
Make the installed libraries, programs and datafiles relocatable;
this means that they may be moved from their installation prefix to
another location without breaking them. If OFF, the installation
prefix is assumed to contain the libraries and datafiles. If ON, no
assumptions are made, and a slower fallback is used to introspect
the location. In all cases the location may be set in the
environment to override the compiled-in defaults. This is OFF by
default for a regular build, and ON by default for a superbuild.
sphinx=(ON|OFF)
Build manual pages and HTML documentation with Sphinx. Enabled by
default if Sphinx is autodetected.
sphinx-pdf=(ON|OFF)
Build PDF documentation with Sphinx. Enabled by default if Sphinx
and XeLaTeX are autodetected.
test=(ON|OFF)
Enable unit tests. Tests are enabled by default.
xsdfu-debug=(ON|OFF)
Enable debugging output for the model code generator.
For example, to disable tests, run ``cmake -Dtest=OFF``. Options will
typically be enabled by default if the prerequisites are available.
The installation prefix may be set at this point using
`-DCMAKE_INSTALL_PREFIX=prefix`. The build system and compiler to use
may also be specified. Please see the :program:`cmake` documentation
for further details of all configurable options, and run ``cmake
--help`` to list the available generators for your platform.
If using the superbuild, most of the options above will be available,
and will be passed to the OME-Files build. In addition, the
following options are provided:
build-packages=packages
Build the specified list of packages (semicolon-separated).
Defaults to ``ome-files``. This can include any OME or third-party
packages provided by the superbuild.
build-prerequisites=(ON|OFF)
Build third-party prerequisites in addition to OME prerequisites
such as ome-common and ome-files. Enabled by default. Disable to
build against system libraries, with system python modules and
system tools.
source-cache=directory
Specify a directory in which to store downloaded source files; this
is useful if you need to repeat the build since the source files
will not need downloading again.
build-cache=directory
Specify a directory from which to source pre-built third-party
prerequisites. Useful to save time when rebuilding if the
content of the :file:`superbuild-install` directory is placed
here after building ``third-party-prerequisites``.
python-cache=directory
Specify a directory from which to source pre-built third-party
python prerequisites. Useful to save time when rebuilding if the
content of the :file:`python` directory is placed here after
building ``third-party-prerequisites``.
ome-superbuild_USE_SYSTEM_${package}=(ON|OFF)
Use when ``build-prerequisites`` is enabled. This permits the
selective disabling of the building of particular components, in
order to use the system version of these components. By default,
building of all components is enabled. `${package}` is the component
name. Look in the :file:`packages` directory for a full list of
components.
ome-superbuild_BUILD_${package}=(ON|OFF)
Use when ``build-prerequisites`` is disabled. This permits the
selective enabling of the building of particular components, in
order to use the superbuild version of these components. By
default, building of all components is disabled. `${package}` is the
component name. Look in the :file:`packages` directory for a full
list of components.
C++11
^^^^^
C++11 features such as :cpp:class:`std::shared_ptr` are used when
using a C++11 or C++14 compiler, or when ``-Dcxxstd-autodetect=ON`` is
used and the compiler can be put into a C++11 or C++14 compatibility
mode. When using an older compatbility mode such as C++98, the Boost
equivalents of C++11 library features will be used as fallbacks to
provide the same functionality. In both cases these types are
imported into the :cpp:class:`ome::compat` namespace, for example as
:cpp:class:`ome::compat::shared_ptr`, and the types in this namespace
should be used for portability when using any part of the API which
use types from this namespace.
Unix, Linux and MacOS X
^^^^^^^^^^^^^^^^^^^^^^^
The default generator is ``Unix Makefiles``, and the standard
:envvar:`CXX`, :envvar:`CXXFLAGS` and :envvar:`LDFLAGS` environment
variables may be set to explicitly specify the compiler, compiler
flags and linker flags, respectively. These may be useful for adding
additional ``-I`` and ``-L`` include and library search paths, for
example.
An alternative generator to consider is ``Ninja``. It is recommended
for parallel builds. This is similar to ``Unix Makefiles`` but allows
building with the :program:`ninja` tool in place of :program:`make`.
It is, in general, faster than :program:`make`, and it is also much
nicer when building in parallel since it will automatically adjust the
number of jobs being run, and will also buffer the output for each job
to allow the build log to be readable, rather than interleaving the
output from concurrently running jobs.
If you wish to use an IDE such as Eclipse or KDevelop, alternative
generators are also available, but are not actively tested by the OME
continuous integration system.
Windows
^^^^^^^
On Windows, the generator will require specifying by hand, and this
will configure the version of Visual Studio (or other compiler) to
use. For example, ``-G "Visual Studio 12 Win64"`` will configure for
generating Visual Studio 2013 64-bit solution and project files for
use with the Visual C++ compiler tool :program:`msbuild` or for
opening in the Visual Studio application.
An alternative generator to consider is ``Ninja``. It is much faster
than building the Visual Studio project and solution files with
:program:`msbuild` due to being much more effective at running jobs in
parallel, since :program:`msbuild` only runs project builds in parallel
while :program:`ninja` will run everything in parallel.
:program:`ninja` will also automatically adjust the number of jobs
being run, and will also buffer the output for each job to allow the
build log to be readable. The build log is also much less verbose
than the output from :program:`msbuild`. However, solution and
project files for use within the Visual Studio application are not
generated.
.. note::
There is no need to use the Visual Studio command shell when
running :program:`cmake` with ``Visual Studio`` generators since
the generator specifies the version of Visual Studio to use.
However, the Visual Studio command shell must be used (or a
command shell with the appropriate environment set used) when
using the ``Ninja`` generator, since the same generator is used
for all Visual Studio versions and the specific compiler to use
must be specified.
Building
--------
For all platforms and generators, it should usually be possible to
build using::
% cmake --build
which will invoke the platform- and generator-specific build as
appropriate.
To build the API reference documentation, run::
% cmake --build . --target doc
Unix, Linux and MacOS X
^^^^^^^^^^^^^^^^^^^^^^^
If using ``Unix Makefiles``, simply run::
% make
with any additional options required, for example ``-j`` to enable
parallel building, or ``VERBOSE=1`` to show the details of every
command being executed.
To build the API reference documentation, run::
% make doc
Similarly, if using ``Ninja``, simply run::
% ninja
or to build the API reference, run::
% ninja doc
If using an IDE, open the generated project file and proceed using the
IDE to build the project.
Windows
^^^^^^^
If using one of the ``Visual Studio`` generators, the generated solution
and project files may be opened using the IDE and then built within
the IDE. Alternatively, the solution or project files may be built
directly using the :program:`msbuild` command-line tool inside a
Visual Studio command prompt (or an appropriately configured command
prompt which has run :program:`VCVARSALL.BAT` or equivalent to
configure the environment). Run::
> msbuild <project>.sln /p:Configuration=<configuration>
Where ``<project>`` is the specific package being built, and
``<configuration>`` is the build type, usually ``Debug`` or
``Release``.
If using the ``Ninja`` generator, run the :program:`ninja` command-line
tool inside a Visual Studio command prompt (or an appropriately
configured command prompt which has run :program:`VCVARSALL.BAT` or
equivalent to configure the environment). Run::
> ninja
Testing
-------
For all platforms and generators, it should usually be possible to run
all tests using :program:`ctest`. Run::
% ctest [-C <configuration>]
or to run verbosely::
% ctest -V [-C <configuration>]
Additional flags allow specification of the build configuration to
use, logging, parallel building and other options. Please see the
:program:`ctest` documentation for further details. Running
:program:`ctest` directly is preferred over the methods detailed below
since passing options works in all cases, and it is also possible to
specify the build configuration (used on Windows).
Individual test programs may be run by hand if required.
Unix, Linux and MacOS X
^^^^^^^^^^^^^^^^^^^^^^^
To run all tests, run::
% cmake --build . --target test
If using ``Unix Makefiles``, simply run::
% make test
or verbosely::
% make test ARGS=-V
If using ``Ninja``, simply run::
% ninja test
Windows
^^^^^^^
To run all tests, if using a ``Visual Studio`` generator, run::
> msbuild RUN_TESTS.vcproj
If using ``Ninja``, simply run::
> ninja test
Installation
------------
Unix, Linux and MacOS X
^^^^^^^^^^^^^^^^^^^^^^^
To install the headers and libraries directly on the system into the
configured prefix::
% cmake --build . --target install
Alternatively, to install into a staging directory::
% cmake --build . --target install -- DESTDIR=/path/to/staging/directory install
If using ``Unix Makefiles``, simply run::
% make install
Alternatively, to install into a staging directory::
% make DESTDIR=/path/to/staging/directory install
If using ``Ninja``, simply run::
% ninja install
Windows
^^^^^^^
When using a ``Visual Studio`` generator, there should be an
:file:`INSTALL.vcxproj` project which may be run using
:program:`msbuild`, for example::
> msbuild INSTALL.vcxproj /p:platform=x64
The ``INSTALL`` project may also be built within the Visual Studio
application.
If using ``Ninja``, simply run::
> ninja install
Installation layout
^^^^^^^^^^^^^^^^^^^
A typical installation layout::
$CMAKE_INSTALL_PREFIX
├── bin
├── include
│ └── ome
│ ├── common
│ ├── compat
│ ├── files
│ └── xml
├── lib
├── libexec
└── share
├── icons
├── man
└── xml
Using the library
-----------------
The :doxygen:`Doxygen API reference <annotated.html>` is used to
document all aspects of the OME-Files API.