Build Instructions¶
The C++ Micro Services library provides CMake build scripts which allow the generation of platform and IDE specific project or Make files.
Prerequisites¶
- CMake 3.2 (users of the latest Visual Studio should typically also use the latest CMake version available)
Configuration¶
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.
Note
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 docs.cppmicroservices.org.
US_BUILD_DOC_MAN Build the man pages. This is typically only enabled on a Unix-like system.
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.
Note
Building the documentation requires
- a Python installation,
- the Doxygen tool,
- the Sphinx documentation generator,
- and the breathe and Read the Docs Sphinx Theme Sphinx extensions
After installing Python and Doxygen, the remaining dependencies
can be installed using pip
:
python -m pip install sphinx breathe sphinx_rtd_theme
Building¶
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
Integration¶
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:
project(CppMicroServicesExamples)
set(CMAKE_CXX_STANDARD_REQUIRED 1)
set(CMAKE_CXX_STANDARD 14)
find_package(CppMicroServices NO_MODULE REQUIRED)
cmake_minimum_required(VERSION ${US_CMAKE_MINIMUM_REQUIRED_VERSION})
cmake_policy(VERSION ${US_CMAKE_MINIMUM_REQUIRED_VERSION})
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
set(_srcs
Activator.cpp
IDictionaryService.cpp
)
# 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 = $(US_CXX)
CXXFLAGS = -g -Wall -Wno-unused -pedantic -fPIC $(US_CXX_FLAGS)
LDFLAGS = -Wl,-rpath="$(CppMicroServices_ROOT)/lib" -Wl,-rpath=.
LDLIBS = "${US_CPPMICROSERVICES_TARGET}"
INCLUDEDIRS = -I"$(CppMicroServices_ROOT)/include/cppmicroservices$(CPPMICROSERVICES_MAJOR_VER)"
LIBDIRS = -L"$(CppMicroServices_ROOT)/lib" -L.
RC = "$(CppMicroServices_ROOT)/bin/usResourceCompiler$(CPPMICROSERVICES_MAJOR_VER)"
OBJECTS = bundle.o IDictionaryService.o
all : main libbundle.so
main: libbundle.so main.o
$(CXX) -o $@ $^ $(CXXFLAGS) $(LDFLAGS) $(INCLUDEDIRS) $(LIBDIRS) $(LDLIBS) -lbundle
libbundle.so: $(OBJECTS) resources.zip
$(CXX) -shared -o $@ $(OBJECTS) $(CXXFLAGS) $(LDFLAGS) $(INCLUDEDIRS) $(LIBDIRS) $(LDLIBS)
$(RC) -z resources.zip -b $@
main.o: main.cpp
$(CXX) $(CXXFLAGS) -DUS_BUNDLE_NAME=main $(INCLUDEDIRS) -c $< -o $@
%.o: %.cpp
$(CXX) $(CXXFLAGS) -DUS_BUNDLE_NAME=bundle $(INCLUDEDIRS) -c $< -o $@
resources.zip: resources/manifest.json
$(RC) -m $< -n bundle -o resources.zip
.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 bundle initialization code for the
libbundle.so
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"
CPPMICROSERVICES_INITIALIZE_BUNDLE
See also
See the Getting Started section and the general Framework documentation to learn more about fundamental concepts.