Context Navigation

OMERO C++ Language Bindings

Prepairing to build
Building the library
Further build configuration
Using the library
A trivial example: yourcode.cpp
Compiling and running yourcode
Notes for Mac users
Notes for Visual Studio users
Further information

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 handful of platforms:

Prepairing to build

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

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

./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++ bindings use Scons as a build system. Scons provides several hooks into its operation.

The following environment variables as defined in source:ome.git/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). (":" or ";" separator depending on platform)
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), separated by ":" or ";" as with CPPPATH.
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.
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.

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>
#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 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

Attachments

Makefile (681 bytes) - added by jmoore 3 years ago. Example Makefile
yourcode.cpp (877 bytes) - added by jmoore 3 years ago. Example source code

Download in other formats:

Plain Text