-
Notifications
You must be signed in to change notification settings - Fork 257
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.
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 |
- Usage of C++11 features, requiring newer compiler versions (see the README)
- Modularized source code layout for additional standard bundles
- Coverity scan integration
- Extended bundle lifecycle
- Automatic memory management of services via shared pointers
- The
LDAPFilter
class can now match filter strings against bundle manifest headers -
Bundle
andBundleContext
are returned to clients as value types - Support for framework listeners
- Bundle resource access without loading its shared library
- ...
- 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.
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>
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
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.
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 |
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 |
The Any
class gained a new std::string ToJson() const
function.
The LDAPFilter
class gained a new bool Match (const Bundle &bundle) const
function.
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 () |
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) |