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 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 docs.cppmicroservices.org.
US_BUILD_DOC_MAN Build the man pages. This is typically only enabled on a Unix-like system.
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 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
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 11)
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 = 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 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.