Note
This documentation is for the new OMERO 5.2 version. See the latest OMERO 5.1.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.
Ice 3.4 will only build with GCC versions older than 4.6 (it contains broken headers which newer GCC versions will not parse). GCC 4.4 is tested and recommended. This version will also fail to build with LLVM/clang++.
Ice 3.5 will build with any GCC version up to 4.9, the latest stable version; later versions may work, but are untested. This version will also build with LLVM/clang++.
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).
For all build methods, the shared library and examples are always built by default. The unit and integration tests are built if Google test (gtest) is detected.
export GTEST_ROOT=/path/to/gtest
cd /path/to/openmicroscopy
./build.py build-default
./build.py build-cpp [-Dcmake.args="cmake options"]
Set any needed cmake options using the ant cmake.args property, plus any needed environment variables.
For example:
./build.py -Dcmake.args="'-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"
This method is present for backward compatibility with the previous scons build system. While it is possible to customize the build somewhat, some behavior is hardcoded and so this will not be suitable for all situations and is not recommended. Parallel building is also not supported. If you wish to have full control over the C++ build or wish to use a cmake generator to build within an IDE, then running cmake directly is recommended.
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
Running cmake directly allows full use of all command-line options and provides complete flexibility for building, e.g. to enable parallel building as shown above or to use an IDE of choice with an appropriate generator.
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 10 Win64" [cmake options] /path/to/openmicroscopy
This is for a 64-bit Visual Studio 2010 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