Migration Guide to version 3.0

Sascha Zelzer edited this page Feb 9, 2017 · 5 revisions

This document aims at providing a guide for migrating from a 2.x release to a 3.x release. It is incomplete and will be updated incrementally over time. If you run into a particular problem that not covered here and you cannot solve easily on your own, then please enter an issue.

Terminology and Conceptual Changes

Module => Bundle

The term module was replaced with bundle to better align with OSGi terminology. This affects file names, class names, and function names.

2.x 3.0
Module Bundle
ModuleContext BundleContext

New features

Project organization and infrastructure

  • Usage of C++11 features, requiring newer compiler versions (see the README)
  • Modularized source code layout for additional standard bundles
  • Coverity scan integration

API additions and changes

  • Extended bundle lifecycle
  • Automatic memory management of services via shared pointers
  • The LDAPFilter class can now match filter strings against bundle manifest headers
  • Bundle and BundleContext are returned to clients as value types
  • Support for framework listeners
  • Bundle resource access without loading its shared library
  • ...

Removed functionality

  • Custom namespace configuration via CMake. Use C++11 namespace aliases instead.
  • Auto-load of modules. There are plans for similar functionality in a future minor release.

Breaking changes

Header includes

The header files are now by default located in bundle specific sub-directories and their file name does not include the us prefix any more. A typical include statement now looks like this:

#include <cppmicroservices/BundleContext.h>

Mandatory manifest file

Manifest files are now required for each bundle. This may change again in a follow-up release, making manifest files optional for simple bundles.

  • TODO: makefile recipe to auto-generate manifest.json

Bundle (module) life-cycle

Instead of automatically loading modules during static initialization (2.x), bundles now have an explicit life-cycle. They need to be installed and started.

See the Installing and Starting Bundles section in the official documentation for an introduction.

Changes in C++ classes

The top-level namespace has been changed from us to cppmicroservices. Symbols mentioned below for version 2.x are implicitly assumed to be prefixed with us::, whereas symbols for version 3.x are implicitly assumed to be prefixed with cppmicroservices::.


Typically, a global search for us:: and replace with cppmicroservices:: should do the trick. A namespace alias like using us = cppmicroservices will also work.

2.x 3.0
us cppmicroservices
ServiceConstants Constants

2.x ServiceConstants namespace

The free functions in the ServiceConstants namespace were changed to const global variables in enclosed in the Constants namespace.

2.x 3.0
const std::string& ServiceConstants::OBJECTCLASS() static std::string Constants::OBJECTCLASS
const std::string& ServiceConstants::SERVICE_ID() static std::string Constants::SERVICE_ID
const std::string& ServiceConstants::SERVICE_RANKING() static std::string Constants::SERVICE_RANKING()
const std::string& ServiceConstants::SERVICE_SCOPE() static std::string Constants::SERVICE_SCOPE
const std::string& ServiceConstants::SCOPE_SINGLETON() static std::string Constants::SCOPE_SINGLETON
const std::string& ServiceConstants::SCOPE_MODULE() static std::string Constants::SCOPE_MODULE
const std::string& ServiceConstants::SCOPE_PROTOTYPE() static std::string Constants::SCOPE_PROTOTYPE

Any class

The Any class gained a new std::string ToJson() const function.

LDAPFilter class

The LDAPFilter class gained a new bool Match (const Bundle &bundle) const function.

MakeInterfaceMap class template

The MakeInterfaceMap class template now uses shared pointers:

2.x 3.0
MakeInterfaceMap(Impl*) MakeInterfaceMap(const std::shared_ptr& impl)
MakeInterfaceMap(ServiceFactory*) MakeInterfaceMap(const std::shared_ptr&)
operator InterfaceMap () operator InterfaceMapPtr ()

Changes in Macros

Most macros were renamed to contain the CPPMICROSERVICES prefix instead of US.

2.x 3.0
US_IMPORT_MODULE_RESOURCES removed, use the usFunctionEmbedResources CMake function with static library file or target name as a parameter to ZIP_ARCHIVES
US_LOAD_IMPORTED_MODULES_INTO_MAIN removed, use explicit Bundle::Start() calls
US_LOAD_IMPORTED_MODULES removed, use explicit Bundle::Start() calls
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.