Building
========

Sources
-------

Download the super-build source release or clone the git repository.
The :downloads_cpp:`downloads page <>` provides links to both source
releases and links to the git repositories for both the super-build
and the individual C++ components.  If you wish to build a specific
release, the corresponding source release or git tag 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.

Errata
------

Before proceeding, please check the :ref:`errata` for known problems
with certain libraries and platforms.

Build environment
-----------------

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.  This is the
approach taken by the author for routine development, since different
configurations may be selected for different projects.

- Activate a python virtualenv if needed
- Ensure that needed tools are on the user :envvar:`PATH`
  (e.g. :program:`cmake`, :program:`doxygen`, :program:`dot`,
  :program:`git`, :program:`python`, :program:`sphinx`)
- 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`

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 source tree.  However, the
source directory itself 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:

build-packages=package1[;package2[;[packagen]]
  A semicolon-separated list of packages to build.  The default is
  ``ome-files``.  Any of the packages in the :file:`packages`
  subdirectory may be specified.
build-prerequisites=(ON|OFF)
  Enable (default) or disable the building of third-party
  dependencies.  If disabled, required dependencies of any of the
  packages to be built (specified with ``build-packages``) must be
  provided by the system, and optional dependencies will be ignored.
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.
head=(ON|OFF)
  Force building from the current git ``master`` branch.  Disabled by
  default.  :program:`git` is required to clone the repositories if
  enabled.
parallel=(ON|OFF)
  Build subcomponents in parallel and run CMake tests in parallel (ON
  by default).  Note this does not control whether the build tool in
  use is building in parallel.  Rather, this controls whether other
  build tools used by subsidiary builds to also build in parellel when
  possible (e.g. boost b2, msbuild).  Its purpose is to allow such
  additional parallelism to be disabled on resource-constrained
  systems.
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
  (default), 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.
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:`stage` directory is placed here after
  building ``third-party-prerequisites``.
ome-cmake-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-cmake-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.

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 14 Win64"`` will configure for
generating Visual Studio 2015 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
-------

The super-build will run unit tests for each component after they are
built.  It is possible to run tests by hand within the build directory
of each component, though this may require environment variables such
as :envvar:`PATH`, :envvar:`LD_LIBRARY_PATH`,
:envvar:`DYLD_FALLBACK_LIBRARY_PATH` and :envvar:`OME_HOME` to be set,
so that the programs, libraries and datafiles in the super-build's
installation staging directory may be found by the tests.

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

Using the library
-----------------

The :ome_files_api:`OME Files C++ API reference <annotated.html>` is
used to document all aspects of the OME-Files API.  Likewise there
are companion references for the
:ome_common_api:`OME Common <annotated.html>` and
:ome_xml_api:`OME XML <annotated.html>` components.

Example scenarios
-----------------

Building OME Files on Unix (release)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the downloaded source release and make.  Run::

    mkdir build
    cd build
    cmake -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/sources
    make
    make install

Building OME Files on Unix (development)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the super-build git repository and ``Ninja``.  Run::

    mkdir build
    cd build
    cmake -G Ninja -Dhead:BOOL=ON -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/git/repo
    make
    make install

Building OME QtWidgets on Unix (development, specific branches)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the super-build git repository and ``Ninja``, and also
requesting that no third party prerequisites should be built *except*
for ``gtest``.  For each component to build, ensure you have a local
git clone and that each clone has the branch you wish to build checked
out.  Run::

    mkdir build
    cd build
    cmake -G Ninja -Dome-common-dir=/path/to/ome-common-cpp -Dome-model-dir=/path/to/ome-model -Dome-files-dir=/path/to/ome-files -Dome-qtwidgets-dir=/path/to/ome-qtwidgets -Dbuild-prerequisites=OFF -Dome-cmake-superbuild_BUILD_gtest=ON -Dbuild-packages=ome-qtwidgets -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/git/repo
    make
    make install

Note that if all the git repositories are in a common location and use
their canonical names, then this may be simplified::

    cmake -G Ninja -Dgit-dir=/path/to/git/repos -Dbuild-prerequisites=OFF -Dome-cmake-superbuild_BUILD_gtest=ON -Dbuild-packages=ome-qtwidgets -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/git/repo

Building OME Files on Windows (release)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the downloaded source release and make.  In a suitable Visual
Studio command prompt, run::

    mkdir build
    cd build
    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/sources
    ninja
    ninja install

Building OME Files on Windows (development)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the super-build git repository and ``Ninja``.  Run::

    mkdir build
    cd build
    cmake -G Ninja -Dhead:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/sources
    ninja
    ninja install

Building OME QtWidgets on Windows (development, specific branches)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the super-build git repository and ``Ninja``.  For each
component to build, ensure you have a local git clone and that each
clone has the branch you wish to build checked out.  Run::

    mkdir build
    cd build
    cmake -G Ninja -Dome-common-dir=/path/to/ome-common-cpp -Dome-model-dir=/path/to/ome-model -Dome-files-dir=/path/to/ome-files -Dome-qtwidgets-dir=/path/to/ome-qtwidgets -Dbuild-packages=ome-qtwidgets -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/sources
    ninja
    ninja install

Note that if all the git repositories are in a common location and use
their canonical names, then this may be simplified::

    cmake -G Ninja -Dgit-dir=/path/to/git/repos -Dbuild-packages=ome-qtwidgets -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/install/dir /path/to/superbuild/sources