Migration Guide to version 3.0

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::.

Namespaces

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_EXPORT_MODULE_ACTIVATOR	CPPMICROSERVICES_EXPORT_BUNDLE_ACTIVATOR
US_IMPORT_MODULE	CPPMICROSERVICES_IMPORT_BUNDLE
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
US_INITIALIZE_MODULE	CPPMICROSERVICES_INITIALIZE_BUNDLE
US_INITIALIZE_EXECUTABLE	CPPMICROSERVICES_INITIALIZE_BUNDLE
US_DECLARE_SERVICE_INTERFACE	CPPMICROSERVICES_DECLARE_SERVICE_INTERFACE (usage now optional)