Note
This documentation is for the new OMERO 5.3 version. See the latest OMERO 5.2.x version or the previous versions page to find documentation for the OMERO version you are using if you have not upgraded yet.
Using the Ice C++ language mapping from ZeroC, OMERO provides native access to your data from C++ code. CMake is used for building the C++ bindings.
Binaries are not provided, therefore it will be necessary for you to compile your own.
Note
Users of Visual Studio with Ice 3.6 will encounter this error while building OmeroCpp: LINK : fatal error LNK1189: library limit of 65535 objects exceeded and will be unable to build OMERO C++ language bindings for Windows as a result of a 16-bit limitation in the Windows PE-COFF executable format used for DLLs, even on 64-bit systems. Workarounds include:
If you are restricted to a specific 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 to acquire the source code. Be sure that the git branch you are using matches the version of your server!
The location of your Ice installation should be automatically detected if installed into a standard location. If this is not the case, set the location of your Ice installation using the ICE_HOME environment variable or the -DICE_HOME or -DIce_SLICE_DIR cmake options for your Ice installation (see below). 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 on your system.
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 X with homebrew:
export ICE_HOME=/usr/local/Cellar/ice/3.5.1
Windows using Visual Studio:
set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.5.1
Note
If the Ice headers and libraries are not automatically discovered, these will need to be specified using appropriate cmake options (see below).
The shared library and examples are always built by default. The unit and integration tests are built if Google test (gtest) is detected.
On Linux, Unix or MacOS X with make:
export GTEST_ROOT=/path/to/gtest
mkdir omero-build
cd omero-build
cmake [-Dtest=(TRUE|FALSE)] [cmake options] /path/to/openmicroscopy
make
For example:
cmake "-DCMAKE_CXX_FLAGS=$CMAKE_CXX_FLAGS" \
"-DCMAKE_EXE_LINKER_FLAGS=$CMAKE_LD_FLAGS" \
"-DCMAKE_MODULE_LINKER_FLAGS=$CMAKE_LD_FLAGS" \
"-DCMAKE_SHARED_LINKER_FLAGS=$CMAKE_LD_FLAGS" \
-DCMAKE_VERBOSE_MAKEFILE:BOOL=ON /path/to/openmicroscopy
make -j8
If you would like to build the C++ tests, run the above with the GTEST_ROOT environment variable set.
Note
When cmake is run, it will run ./build.py build-default in the openmicroscopy source tree to generate some of the C++ and Ice sources. If you have previously done a build by running ./build.py, this step will be skipped. However, if you have recently switched branches without cleaning the source tree, please run ./build.py clean in the source tree to clean up all the generated files prior to running cmake.
If the build fails with errors 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.
cmake supports configuration of the build using many different environment variables and options; for a full list, see the cmake reference documentation. The following environment variables are commonly needed:
Directories to be searched for include files, for example
/opt/Ice-3.5.1/include
A : or ; separator character is used to separate directories, depending on the platform. Note these are used only for feature tests, not for passing to the compiler when building, for which CMAKE_CXX_FLAGS is needed.
Directories to be searched for libraries, for example
/opt/Ice-3.5.1/lib
Directories are separated by : or ; as with CMAKE_INCLUDE_PATH. Note these are used only for feature tests and finding libraries, not for passing to the linker when building, for which CMAKE_*_LINKER_FLAGS is needed.
In addition, cmake options may be defined directly when running cmake. Commonly needed options include:
cmake offers many additional options. Please refer to the documentation for further details, in particular to the variables which change the behavior of the build.
Warning
OMERO.cpp will not currently build on Windows due to exceeding DLL symbol limits on this platform, leading to a failure when linking the DLL. It is hoped that this platform limitation can be worked around in a future OMERO release.
cmake has full support for Visual Studio. Use the cmake -G option to set the generator for your Visual Studio version, with a Win64 suffix for an x64 build. The correct Ice programs and libraries for your Ice installation should be automatically discovered.
cmake -G "Visual Studio 11 Win64" [cmake options] /path/to/openmicroscopy
This is for a 64-bit Visual Studio 2012 build. Modify appropriately for other versions and compilers. Running
cmake --help
will list the available generators for your platform (without the Win64 suffix).
Once cmake has finished running, the generated project and solution files may be then opened in Visual Studio, or built directly using the msbuild command-line tool (make sure that the Visual Studio command prompt matches the generator chosen) or by running:
cmake --build .
As for the Unix build, above, it is also possible to build on Windows using build.py or ant, providing that you configure the generator appropriately using the correct cmake options. However, this will not work for all generators reliably, and the Windows shell quoting makes passing nested quotes to ant quite tricky, so running cmake by hand is recommended.
Note
It may be necessary to specify /Zm1000 as an additional compiler setting.
If using make, run:
make [DESTDIR=/path/to/staging/directory] install
If using another build system, please invoke the equivalent install target for that system.
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/share/Ice
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
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, download the two files above (Makefile and yourcode.cpp) and then in a 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
Note
This example explains how to run on Linux only. For doing the same on MacOS X, change all instances of LD_LIBRARY_PATH to DYLD_LIBRARY_PATH.
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 64-bit support