OMERO

Downloads
Feature List
Licensing

Page Contents

Previous topic

OMERO Matlab language bindings

Next topic

Local analysis

This Page

This documentation is for OMERO 4.4 and is no longer being updated, to see the documentation for the latest release, refer to http://openmicroscopy.org/site/support/omero/

OMERO C++ language bindings

Using the Ice C++ language mapping from ZeroC, OMERO provides native access to your data from C++ code. The build-cpp build target produces a platform-dependent shared library which can be linked to your application.

Binaries are not provided, therefore it will be necessary for you to compile your own.

Prerequisites

  • The OMERO source code
  • A C++ compiler
    • GCC is recommended for Linux and MacOS X
    • Visual Studio or the Platform SDK for Windows
  • The ZeroC Ice libraries, headers and slice definitions

Restrictions

Ice 3.3 and Ice 3.4 will only build with GCC versions older than 4.6 (they contain broken headers which newer GCC versions will not parse). GCC 4.4 is tested and recommended.

Ice 3.5 will build with any GCC version up to 4.8, the latest stable version; later versions may work, but are untested.

The version of GCC and/or Ice provided on your system should be compatible, but if you are restricted to a particular version of GCC or Ice, you may need to obtain or build a compatible version of Ice or GCC, respectively.

Preparing to build

Begin by following the instructions under Checking out the source code on acquiring the source code. Be sure that the git branch you are using matches the version of your server!

Set the ICE_HOME environment variable for your installation. This location varies depending upon the installation location and Ice version in use. Some possible locations for the 3.5.0 version of Ice follow. Note these are just examples; you need to adjust them for the Ice installation path and version in use.

  • Ice built from source and installed into /opt:

    export ICE_HOME=/opt/Ice-3.5.0
    
  • Ice installed on Linux using RPM packages:

    export ICE_HOME=/usr/share/Ice-3.5.0
    
  • MacOS with homebrew:

    export ICE_HOME=/usr/local/Cellar/ice/3.5.0
    
  • Windows using Visual Studio:

    set ICE_HOME=C:Ice-3.5.0
    

Users of a package manager will also need to set ICE_HOME if the Ice paths are not automatically detected correctly. The slice2xxx tools generally don’t pick up the location of the slice definitions by default if this is unset.

Note

If the Ice headers and libraries are not present on the standard search paths, these will need to be specified using the CPPPATH and LIBPATH environment variables (see below).

Windows users building with Visual Studio will also need to run the Visual Studio environment setup scripts:

C:\Documents and Settings\USER>c:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat
Setting environment for using Microsoft Visual Studio 2008 x86 tools.

or otherwise guarantee that the your environment is properly configured. For the 64bit build, be sure to use the right setup, namely Start‣Microsoft Visual Studio 2008‣Visual Studio Tools‣Visual Studio +2008 Command Prompt.

Building the library

To build the C++ dynamic library:

cd omero
./build.py
./build.py build-cpp

or

./build.py build-all

If you would like to build the C++ tests, you can run:

./build.py test-compile-all
./build.py test-unit

or to test only C++:

./build.py -f components/tools/OmeroCpp/build.xml test

Note

If you would like to work on just the C++ code without worrying about the rest of the build, you can install scons and use it directly. Alternatively, you can use the scons version which comes with the OMERO source code:

cd components/tools/OmeroCpp && python ../../../target/scons/scons.py test

This does require having run the top-level build (build.py) at least once.

Note

If the build fails with errors such as

Checking for C++ header file Ice/Ice.h... no
Fatal Error: Ice/Ice.h not found

this can be caused by the Ice headers not being installed or not being on the search path. However, also check components/tools/OmeroCpp/config.log. If this contains error messages such as

/usr/include/Ice/ProxyHandle.h:176:13: error: ‘upCast’ was not declared in this scope,
and no declarations were found by argument-dependent lookup at the point of
instantiation

this is caused by the Ice headers being buggy, and newer versions of GCC rejecting the invalid code. To compile in this situation, add -fpermissive to CXXFLAGS to allow the invalid code to be accepted, but do note that this may also mask other problems so should not be used unless strictly needed.

Further build configuration

The C++ bindings use scons as a build system. scons provides several hooks into its operation. The following environment variables as defined in components/blitz/blitz_tools.py are considered:

ARCH
Either x86 or x64. x64 will be used by default on a 64-bit machine, otherwise x86
CPPPATH

directories to be searched for include files, for example

-I/opt/Ice-3.5.0/include

A : or ; separator character is used to separate directories, depending on the platform.

CXXFLAGS
standard make-like CXXFLAGS variable
CXX
compiler executable. Useful with ccache.
LIBPATH

directories to be searched for libraries, for example

-L/opt/Ice-3.5.0/lib

Directories are separated by : or ; as with CPPPATH.

ICE_HOME
your Ice installation. The contained include directory will be added to your CPPPATH, but the contained lib directory will not be added to your LIBPATH since this may not contain the needed 32- or 64-bit libraries; this will need setting with the correct value for your system.
J
specifies the number of concurrent build tasks as with make.
RELEASE
debug or Os (i.e. optimize for size). debug is used by default.
VERBOSE
show the actual build commands rather than the pretty “Compiling XYZ…” statements.

Zip files containing the C++ header files, the libraries, and source code are placed under OMERO_HOME/target with other zip artifacts.

Note

If you are using make, you can unpack the main zip (e.g. OMERO.cpp-<version>-64dbg.zip) to some directory (OMERO_DIST) and follow the instructions below to get started. For help with other build systems, please contact the mailing list.

Using the library

To use OMERO C++ language bindings it is necessary to point your compiler and linker at the mentioned directories above. A simple GNU make Makefile might look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#
# MAKEFILE:
#
# Where the OMERO distribution was installed
OMERO_DIST?=/opt/omero

# Where the Ice lib/ and include/ directories are to be found
ICE_HOME?=/usr

INCLUDES=-I$(OMERO_DIST)/include -I$(ICE_HOME)/include 

LIBS=-L$(OMERO_DIST)/lib -L$(ICE_HOME)/lib -L$(ICE_HOME)/lib64 \
     -lIce -lIceUtil -lGlacier2 -lomero_client -lstdc++

LIBPATH=$(LD_LIBRARY_PATH):$(ICE_HOME)/lib:$(ICE_HOME)/lib64:$(OMERO_DIST)/lib

.PHONY: clean run

yourcode.o: yourcode.cpp
	$(CXX) $(CXXFLAGS) -c -o $@ $< $(INCLUDES)

yourcode: yourcode.o
	$(CXX) -o $@ $^ $(LIBS)

run:  yourcode
	LD_LIBRARY_PATH="$(LIBPATH)" ./yourcode --Ice.Config=../etc/ice.config

clean:
	rm -f yourcode *.o *~ core 

A trivial example: yourcode.cpp

And a simple example file might looking something like the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
//
// yourcode.cpp:
//

// Domain
#include <omero/client.h>
#include <omero/api/IAdmin.h>
// Std
#include <iostream>
#include <cassert>
#include <vector>
#include <time.h>
#include <map>

using namespace std;

/*
 * Pass "--Ice.Config=your_config_file" to the executable, or
 * set the ICE_CONFIG environment variable.
 */
int main(int argc, char* argv[])
{
    omero::client_ptr omero = new omero::client(argc, argv);
    omero::api::ServiceFactoryPrx sf = omero->createSession();
    sf->closeOnDestroy();

    // IAdmin is responsible for all user/group creation, password changing, etc.
    omero::api::IAdminPrx  admin  = sf->getAdminService();

    // Who you are logged in as.
    cout << admin->getEventContext()->userName << endl;

    // These two services are used for database access
    omero::api::IQueryPrx  query  = sf->getQueryService();
    omero::api::IUpdatePrx update = sf->getUpdateService();

    return 0;
}

This code does not do much. It creates a server session, loads a few services, and prints the user’s name. For serious examples, see Working with OMERO.

Compiling and running your code

Therefore, to compile and run yourcode, you will need to download the two files above (Makefile and yourcode.cpp) and then from the shell:

make OMERO_DIST=dist yourcode
LD_LIBRARY_PATH=dist/lib ./yourcode --Ice.Config=dist/etc/ice.config

where you have edited dist/etc/ice.config to contain the values:

omero.host=localhost
omero.user=your_name
omero.pass=your_password

Alternatively, you can pass these on the command-line:

LD_LIBRARY_PATH=dist/lib ./yourcode omero.host=localhost --omero.user=foo --omero.pass=bar

Notes for Mac users

This example explains how to build on Linux only. For doing the same on Mac OS X, change all instances of LD_LIBRARY_PATH to DYLD_LIBRARY_PATH.

Notes for Visual Studio users

The SConstruct build file in OMERO C++ language bindings defines a target msproj which can be used to generate an MS Visual Studio project and solution. There is also a similarly named ant target:

build -f components\tools\OmeroCpp\build.xml msproj

Note

It may be necessary to specify /Zm1000 as an additional compiler setting.

Further information

For the details behind writing, configuring, and executing a client, please see Working with OMERO.