Build Instructions

The C++ Micro Services library provides CMake build scripts which allow the generation of platform and IDE specific project or Make files.


  • CMake 3.2 (users of the latest Visual Studio should typically also use the latest CMake version available)


When building the C++ Micro Services project, you have a few configuration options at hand.

  • CMAKE_INSTALL_PREFIX The installation path.

  • US_ENABLE_THREADING_SUPPORT Enable the use of synchronization primitives (atomics and pthread mutexes or Windows primitives) to make the API thread-safe. All documented guarantees of thread-safety are valid if and only if this option is turned ON. If your application is not multi-threaded, turn this option OFF to get maximum performance.


    In version 3.0 this option only supports the ON value. A follow-up release will restore the single-threaded configuration.

  • US_BUILD_SHARED_LIBS Specify if the library should be build shared or static. See Static Bundles for detailed information about static CppMicroServices bundles.

  • US_BUILD_TESTING Build unit tests and code snippets.

  • US_BUILD_EXAMPLES Build the tutorial code and other examples.

  • US_BUILD_DOC_HTML Build the html documentation, as seen on

  • US_BUILD_DOC_MAN Build the man pages. This is typically only enabled on a Unix-like system.


Building the documentation requires

After installing Python and Doxygen, the remaining dependencies can be installed using pip:

python -m pip install sphinx breathe sphinx_rtd_theme


After configuring a build directory with CMake, the project can be build. If you chose e.g. Unix Makefiles, just type:

make -j

in a terminal with the current directoy set to the build directory. To install the libraries, header files, and documentation into the configured CMAKE_INSTALL_PREFIX type:

make install


Projects using the C++ Micro Services library need to set-up the correct include paths and link dependencies. Further, each executable or library which needs a BundleContext must contain specific initialization code, a manifest.json resource, and must be compiled with a unique US_BUNDLE_NAME pre-processor definition. See Getting Started for an introduction to the basic concepts.

The C++ Micro Services library provides CMake Support 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:



find_package(CppMicroServices NO_MODULE REQUIRED)


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 bundle
set(_lib_name dictionaryservice)

# A list of source code files

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

# Generate bundle initialization code
usFunctionGenerateBundleInit(TARGET Tutorial-${_lib_name} OUT _srcs)

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

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

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

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

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

The call to usFunctionGenerateBundleInit generates the proper bundle initialization code and provides access to the bundle specific BundleContext instance. Further, the set_property command sets the US_BUNDLE_NAME definition.

Makefile based projects

The following Makefile is located at /doc/src/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${US_DEBUG_POSTFIX}

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

RC = "$(CppMicroServices_ROOT)/bin/usResourceCompiler3"

OBJECTS = bundle.o IDictionaryService.o

all : main

main: main.o
	$(RC) -z -b $@ 

main.o: main.cpp

%.o: %.cpp
	$(CXX) $(CXXFLAGS) -DUS_BUNDLE_NAME=bundle $(INCLUDEDIRS) -c $< -o $@ resources/manifest.json
	$(RC) -m $< -n bundle -o 

.PHONY : 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 bundle initialization code for the shared library is generated by using the CPPMICROSERVICES_INITIALIZE_BUNDLE pre-processor macro at the end of the bundle.cpp source file (any source file compiled into the bundle would do):

#include "cppmicroservices/BundleInitialization.h"


See also

See the Getting Started section and the general Framework documentation to learn more about fundamental concepts.