OMERO C++ Language Bindings

Using the  Ice C++ language mapping from  http://zeroc.com, 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.

As of milestone:Beta4.1, binaries are not provided and so it will be necessary to compile your own. Test versions are, however, built on a small handfull of platforms:

• Windows:  http://hudson.openmicroscopy.org.uk/job/omero-windows-dll (or  Beta4.1)
• Linux:  http://hudson.openmicroscopy.org.uk/job/OMERO (or  Beta4.1)

Prepairing to build

Begin by following the instructions under OmeroContributing on acquiring the source code. Be sure that the subversion path you are using matches the version of your server!

# Either
  svn co http://cvs.openmicroscopy.org.uk/svn/omero/trunk omero

# or
  svn co http://cvs.openmicroscopy.org.uk/svn/omero/branches/Beta4.0 omero

If you did not install Ice via a package manager like APT on Debian/Ubuntu, RPM on Centos/RHEL or Macports on Mac OS X, you will need to manually set the ICE_HOME environment variable for your installation:

export ICE_HOME=/opt/Ice-3.3

or on Windows either

set ICE_HOME=c:\Ice-3.3.1

for Visual Studio 2005, or

set ICE_HOME=c:\Ice-3.3.1-VC90

for Visual Studio 2008.

Additionally on Windows, you will 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" or "...->Visual Studio 2008 x64 Win64 Command Prompt".

Building the library

Then, 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 will need to install  boost_unit_test-mt and run:

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

or to test only C++:

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

Information on installing Boost on Windows is available at  http://www.boost.org/doc/libs/1_39_0/more/getting_started/windows.html

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.

Further build configuration

As mentioned above, the C++ use  Scons as a build. Scons provides several hooks into its operation.

The following environment variables as defined in source:trunk/components/blitz/build_tools.py are considered:

• ARCH - Either "x86" or "x64". "x64" will be used by default on a 64bit machine, otherwise "x86"
• CPPPATH - directories to be searched for include files (-I/opt/Ice-3.3.0/includes). The pla
• CXXFLAGS - standard make-like CXXFLAGS variable
• CXX - compiler executable. Useful with  ccachetform path separator ":" or ";" is used.
• LIBPATH - directories to be searched for libraries (-L/opt/Ice-3.3.0/lib). The platform path
• ICE_HOME - your Ice installation. lib and include will be added to your LIBPATH and CPPPATH
• J - specifies to concurrently build tasks as with Make. When using scons directly, use t separator ":" or ";" is used.
• 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.he argument "-j".

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

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 get started. For help with other build systems, please contact the mailing list.

Using the library

To use OmeroCpp it is necessary to point your compiler and linker at the mentioned directories above. A simple Gnu  Makefile might look like this (download ):

#
# MAKEFILE:
#
# Where the OMERO C++ distribution was installed.
OMERO_DIST?=/opt/OMERO.cpp-64dbg

# 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 (download ):

//
// yourcode.cpp:
//

// Domain
#include <omero/client.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 omero(argc, argv);
    omero::api::ServiceFactoryPrx sf = omero.createSession();

    // 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; // session is closed by destructor. or call omero.closeSession();
}

This code doesn't do much. It creates a server session, loads a few services, and prints the user's name. For serious examples, see OmeroClients.

Compiling and running yourcode

Therefore, to compile and run yourcode, you'll 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've 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 OmeroCpp/ defines a target "msproj" which can be used to generate an MS VS project and solution. There is also a similarly named ant target:

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

Also:

• 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 OmeroClients.

---

See also:  http://zeroc.com, OmeroBlitz, OmeroGrid, OmeroApi, OmeroBuild, #1596 which added 64bit support