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.12.4 (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 and 3.1 this option only supported the ON value. The OFF configuration is supported again in version 3.2 and later.

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

  • US_ENABLE_ASAN Enable the use of Address Sanitizer in builds of CppMicroServices.


    When this setting is enabled for a CppMicroServices build on Windows, the US_ASAN_USER_DLL needs to be correctly set. This DLL is typically found at the following location ($VS is the root Visual Studio install folder): $VS\2019\Community\VC\Tools\MSVC\<version>\bin\Hostx64\x64\clang_rt.asan_dbg_dynamic-x86_64.dll.

    Additionally, ASAN for Visual Studio is only available in versions 16.9 or later. For more information, please see the Microsoft documentation <>.

  • US_ASAN_USER_DLL The path to the ASAN DLL which Microsoft Visual Studio ships. This value should only be set on Windows.

  • US_ENABLE_TSAN Enable the use of Thread Sanitizer in builds of CppMicroServices. This boolean should only be set on Linux or Mac.

  • US_USE_SYSTEM_GTEST Build using an existing installation of Google Test.

  • GTEST_ROOT Specify the root directory of the Google Test framework installation to use when building and running tests.


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

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

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.