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.
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.
Begin by following the instructions under Installing OMERO from source 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.1 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.1
Ice installed on Linux using RPM packages:
export ICE_HOME=/usr/share/Ice-3.5.1
MacOS with homebrew:
export ICE_HOME=/usr/local/Cellar/ice/3.5.1
Windows using Visual Studio:
set ICE_HOME=C:\Ice-3.5.1
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 does not 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 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.
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
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.
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.
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:
directories to be searched for include files, for example
-I/opt/Ice-3.5.1/include
A : or ; separator character is used to separate directories, depending on the platform.
directories to be searched for libraries, for example
-L/opt/Ice-3.5.1/lib
Directories are separated by : or ; as with CPPPATH.
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.
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 simple example might look 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.
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
This example explains how to build on Linux only. To do the same on Mac OS X, change all instances of LD_LIBRARY_PATH to DYLD_LIBRARY_PATH.
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.
For the details behind writing, configuring, and executing a client, please see Working with OMERO.
See also
Ice, OMERO.grid, OMERO Application Programming Interface, Build System, #1596 which added 64bit support