Getting Started

Projects which want to make use of the capabilities provided by the C++ Micro Services library need to set-up the correct include paths and link dependencies. Further, each executable or shared library which needs a ModuleContext instance must contain specific initialization code and must be compiled with a unique US_MODULE_NAME pre-processor definition. In case of executables, the value is required to be main, e.g. compile the executable with -DUS_MODULE_NAME=main.

The C++ Micro Services library provides CMake utility functions for CMake based projects but there are no restrictions on the type of build system used for a project.

CMake based projects

To easily set-up include paths and linker dependencies, use the common find_package mechanism provided by CMake:

project(CoreExamples)

cmake_minimum_required(VERSION 2.8)

find_package(CppMicroServices NO_MODULE REQUIRED)

include_directories(${CppMicroServices_INCLUDE_DIRS})

The CMake code above sets up a basic project (called CppMicroServicesExamples) and tries to find the CppMicroServices package and subsequently to set the necessary include directories. Building a shared library might then look like this:

# The library name for the module
set(_lib_name dictionaryservice)

# A list of source code files
set(_srcs
  Activator.cpp
  IDictionaryService.cpp
)

# Add a special source file to the _srcs variable that
# will enable dependency checking on module resources.
usFunctionGetResourceSource(TARGET Example-${_lib_name} OUT _srcs)

# Generate module initialization code
usFunctionGenerateModuleInit(_srcs)

# Create the library
add_library(Example-${_lib_name} ${_srcs})

# Add the US_MODULE_NAME target property
set_property(TARGET Example-${_lib_name} APPEND PROPERTY US_MODULE_NAME ${_lib_name})

# Add the required compile definition
set_property(TARGET Example-${_lib_name} APPEND PROPERTY COMPILE_DEFINITIONS US_MODULE_NAME=${_lib_name})

# Embed the manifest file
usFunctionEmbedResources(TARGET Example-${_lib_name} WORKING_DIRECTORY resources FILES manifest.json)

# Link the CppMicroServices library
target_link_libraries(Example-${_lib_name} ${CppMicroServices_LIBRARIES})

The call to usFunctionGenerateModuleInit generates the proper module initialization code and provides access to the module specific ModuleContext instance. Further, the set_propertycommand sets the US_MODULE_NAME definition.

Makefile based projects

The following Makefile is located at examples/makefile/Makefile and demonstrates a minimal build script:

CXX = g++
CXXFLAGS = -g -Wall -Wno-unused -pedantic -fPIC $(US_CXX_FLAGS)
LDFLAGS = -Wl,-rpath="$(CppMicroServices_ROOT)/lib" -Wl,-rpath=.
LDLIBS = -lCppMicroServices

INCLUDEDIRS = -I"$(CppMicroServices_ROOT)/include/CppMicroServices"
LIBDIRS = -L"$(CppMicroServices_ROOT)/lib/CppMicroServices" -L.

all : main libmodule.so

main: libmodule.so main.o
  $(CXX) -o $@ $^ $(CXXFLAGS) $(LDFLAGS) $(INCLUDEDIRS) $(LIBDIRS) $(LDLIBS) -lmodule

libmodule.so: module.o IDictionaryService.o
  $(CXX) -shared -o $@ $^ $(CXXFLAGS) $(LDFLAGS) $(INCLUDEDIRS) $(LIBDIRS) $(LDLIBS)

main.o: main.cpp
  $(CXX) $(CXXFLAGS) -DUS_MODULE_NAME=main $(INCLUDEDIRS) -c $< -o $@

%.o: %.cpp
  $(CXX) $(CXXFLAGS) -DMODULE_EXPORTS -DUS_MODULE_NAME=module $(INCLUDEDIRS) -c $< -o $@

.PHONY : clean

clean:
  rm -f *.o

The variable CppMicroServices_ROOT is an environment variable and must be set to the CppMicroServices installation directory prior to invoking make. The module initialization code for the libmodule.so shared library is generated by using the US_INITIALIZE_MODULE pre-processor macro at the end of the module.cpp source file (any source file compiled into the module would do):

#include <usModuleInitialization.h>

US_INITIALIZE_MODULE