C++ overview ============ A completely native Bio-Formats C++ interface is now available. 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 Java implementation are currently unavailable; the intention is that support for these will be added over time. .. note:: The C++ implementation is functional in Bio-Formats version 5.1. However, API stability will not be guaranteed until version 5.2 since it may be necessary to refactor certain parts of the API for optimal usability, robustness and performance. Applications built against version 5.1 of the API may require updating to work with version 5.2, if they make use of any part of the API which is changed incompatibly. 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:`bf-test 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 Bio-Formats (*BF [super]build*). A subset of these are required for building client applications making use of Bio-Formats (*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. Bio-Formats may be built in two ways. The first is “standalone” (*BF 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” (*BF superbuild*) which builds the prerequisites in addition to Bio-Formats, 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 | BF build | BF 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.0 | 2.8.12 | \• | \• | | | +---------------+--------------+--------------+----------+---------------+--------------+--------+ | 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 2014 | TeXLive 2012 | § | § | | | +---------------+--------------+--------------+----------+---------------+--------------+--------+ \• Required for Bio-Formats build; headers may be needed for client build; libraries and any data files required for deployment ◦ Optional for Bio-Formats build; if used for the Bio-Formats 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 Bio-Formats 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 `__ .. _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 `_ 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 `__ - `Download `__ 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 `__ - `Download `__ - `Extra packages for Windows `__ 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 `__ - `Download `__ 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 `__ An embedded copy of GTest is provided; it is only necessary to use a system-provided or self-built copy of GTest if the embedded copy is not functional on a specific system. If using an external 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 `__ - `Zip download `__ - `SVN tag `__ 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 `__ - `Download `__ 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 `__ - `Download `__ Doxygen ^^^^^^^ +------------------+---------------+ | System | Package | +==================+===============+ | BSD Ports | devel/doxygen | +------------------+---------------+ | Debian/Ubuntu | doxygen | +------------------+---------------+ | Homebrew | doxygen | +------------------+---------------+ | RedHat/CentOS | doxygen | +------------------+---------------+ - `Website `__ - `Download `__ Graphviz ^^^^^^^^ If possible, install the following packages: +------------------+-------------------+ | System | Package | +==================+===================+ | BSD Ports | graphics/graphviz | +------------------+-------------------+ | Debian/Ubuntu | graphviz | +------------------+-------------------+ | Homebrew | graphviz | +------------------+-------------------+ | RedHat/CentOS | graphviz | +------------------+-------------------+ - `Website `__ - `Download (for Windows) `__ 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 `__ - `Download `__ 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 `__ 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) `__ - `TeXLive quick install (for Unix) `__ - `MacTeX website (for MacOS X) `__ - `MacTeX download (for MacOS X) `__ - `MikTeX website (for Windows) `__ - `MikTeX download (for Windows) `__ 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 Bio-Formats 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 Bio-Formats, 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`. Source tree layout ------------------ Source tree layout:: cpp ├── cmake ├── ext ├── lib │ └── ome │ ├── bioformats │ │ ├── detail │ │ ├── in │ │ ├── out │ │ └── tiff │ ├── common │ │ ├── endian │ │ └── xml │ │ └── dom │ ├── compat │ ├── internal │ ├── qtwidgets │ ├── test │ └── xml ├── libexec │ ├── info │ └── view ├── share └── test Top-level directories inside :file:`cpp`: :file:`cmake` CMake build infrastructure :file:`ext` External third-party code :file:`lib` Bio-Formats library headers and sources :file:`libexec` Bio-Formats internal binaries (not direct public API) :file:`share` Bio-Formats architecture-independent data files :file:`test` Bio-Formats unit tests Components in :file:`lib` and :file:`test`: :file:`bioformats` Bio-Formats reader and writer interfaces and implementations :file:`common` Common functionality used by all other components :file:`compat` Compatibility workarounds :file:`internal` Private implementation details :file:`qtwidgets` Qt5 widgets for image rendering with OpenGL :file:`test` Unit test common functions :file:`xml` OME XML model and metadata Configuring ----------- Bio-Formats 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 Bio-Formats 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 /path/to/bioformats 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. embedded-gtest=(ON|OFF) Enable the use of an embedded copy of the Google Test (gtest) library. This is off by default but will be enabled automatically if a system copy is not found. This may be enabled explicitly to override the autodetection. 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. 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. 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: 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. bioformats-superbuild_USE_SYSTEM_${package}=(ON|OFF) Disable 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. 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. 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. If you wish to use an IDE such as Eclipse or KDevelop, an alternative generator may be used. 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 11 Win64"`` will configure for generating Visual Studio 2012 64-bit build files for use with the Visual C++ compiler. .. note:: There is no need to use the Visual Studio command shell when running :program:`cmake`. 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 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 If using an IDE, open the generated project file and proceed using the IDE to build the project. Windows ^^^^^^^ If using Visual Studio, the generated project files may be opened using the IDE and then built within the IDE. Alternatively, the 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). Testing ------- For all platforms and generators, it should usually be possible to run all tests using :program:`ctest`. Run:: % ctest or to run verbosely:: % ctest -V 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. Individual test programs may be run by hand if required. Linux and MacOS X ^^^^^^^^^^^^^^^^^ To run all tests, run:: % cmake --build . --target test or verbosely:: % cmake --build . --target test -- ARGS=-V If using ``Unix Makefiles``, simply run:: % make test or verbosely:: % make test ARGS=-V Windows ^^^^^^^ To run all tests, run:: > msbuild RUN_TESTS.vcproj Installation ------------ 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 Windows ^^^^^^^ When using Visual Studio, there should be an :file:`INSTALL.vcxproj` project which may be run using :program:`msbuild`, for example:: > msbuild INSTALL.vcxproj /p:platform=x64 Installation layout ^^^^^^^^^^^^^^^^^^^ A typical installation layout:: $CMAKE_INSTALL_PREFIX ├── bin ├── include │ └── ome │ ├── bioformats │ ├── common │ ├── compat │ └── xml ├── lib ├── libexec └── share ├── icons ├── man └── xml Using the library ----------------- The :doxygen:`Doxygen API reference ` is used to document all aspects of the Bio-Formats API.