This software is being developed for multiple platforms (Windows, Mac OS X, Linux) using portable C++.
The codebase utilizes a number of great open-source projects (licenses vary). More details are given below.
- The CMake build tools
- The Conan package manager
- A few of the Boost C++ Libraries
- The C++ REST SDK, for client-server communication over REST APIs
- This library incorporates some third-party material including WebSocket++, and also relies on e.g. some of the Boost C++ Libraries and OpenSSL.
- The WebSocket++ header-only C++ websocket client/server library, to implement Query API websocket subscriptions
- For JSON Schema validation, the Modern C++ JSON schema validator library, which is implemented on top of JSON for Modern C++
- For creating and validating JSON Web Tokens, the Thalhammer/jwt-cpp header only library
- For DNS Service Discovery (DNS-SD), the Bonjour SDK on Windows, and on Linux either Avahi or Apple's mDNSResponder (another name for Bonjour)
- The Catch automated test framework, for unit testing
The following instructions describe how to prepare these external dependencies when building this software.
On Windows, Visual Studio 2015 or higher is required.
On Linux, g++
(the GNU project C++ compiler) is supported; the GCC 4.8 release series is tested, although a more recent compiler is to be recommended!
Notes:
- Visual Studio 2013 is not supported, because it does not implement C++11 thread-safe function-local static initialization.
- For the same reason, Visual Studio 2015 onwards with
/Zc:threadSafeInit-
, and GCC with--fno-threadsafe-statics
, are also not supported.
Specific instructions for cross-compiling for Raspberry Pi are also provided.
- Download and install a recent CMake stable release for your platform
Notes:- Currently, CMake 3.24 or higher is required in order to use the Conan package manager; version 3.28.3 (latest release at the time) has been tested
- Pre-built binary distributions are available for many platforms
- On Linux distributions, e.g. Ubuntu 14.04 LTS (long-term support), the pre-built binary version available via
apt-get
may be too out-of-date
Fetch, build and install a suitable version:wget "https://cmake.org/files/v3.24/cmake-3.24.2.tar.gz" tar -zxvf cmake-3.24.2.tar.gz cd cmake-3.24.2 ./bootstrap make sudo make install cd ..
- Some CMake modules derived from third-party sources are supplied in the third_party/cmake directory
By default nmos-cpp uses Conan to download most of its dependencies.
- Install Python 3 if necessary
Note: The Python scripts directory needs to be added to thePATH
, so the Conan executable can be found - Install or upgrade Conan using
pip install --upgrade conan~=2.0.5
Notes:- On some platforms with Python 2 and Python 3 both installed this may need to be
pip3 install --upgrade conan~=2.0.5
- Conan 2.0.5 or higher is required; dependencies may require a higher version; version 2.0.17 (latest release at the time) has been tested
- Conan 1.X is no longer supported
- On some platforms with Python 2 and Python 3 both installed this may need to be
- Install a DNS Service Discovery implementation, since this isn't currently handled by Conan
Now follow the Getting Started instructions directly. Conan is used to download the rest of the dependencies.
If you prefer not to use Conan, you must install Boost, WebSocket++, OpenSSL and C++ REST SDK as detailed below.
If using Conan, this section can be skipped.
If not using Conan...
- Download a recent release
Notes:- Several Boost releases have been tested, including Version 1.83.0 (latest release at the time) and Version 1.54.0
- On Linux distributions, a Boost libraries package may already be installed, e.g. Ubuntu 14.04 LTS has Version 1.54.0
- Expand the archive so that, for example, the boost_1_83_0 directory is at the same level as the nmos-cpp directory
- Build and stage (or install) the following Boost libraries for your platform/toolset:
- atomic
- chrono
- date_time
- regex
- system
- thread
For example, on Windows, for Visual Studio 2019:
bootstrap
b2 toolset=msvc-14.2 ^
--prefix=. ^
--with-atomic ^
--with-chrono ^
--with-date_time ^
--with-regex ^
--with-system ^
--with-thread ^
--stagedir=x64 ^
stage ^
address-model=64
For example, on Linux:
./bootstrap.sh
sudo ./b2 \
'--prefix=`pwd`' \
--with-atomic \
--with-chrono \
--with-date_time \
--with-filesystem \
--with-random \
--with-regex \
--with-system \
--with-thread \
--stagedir=. \
stage
If using Conan, this section can be skipped.
If not using Conan...
- Get the source code
- Clone the repo and its submodules, and check out the v2.10.19 tag
Thegit clone
command option--recurse-submodules
(formerly--recursive
) simplifies cloning a project with submodules.
For example:Note: The downloadable archives created by GitHub cannot be used on their own since they don't include submodules.git clone --recurse-submodules --branch v2.10.19 https://github.com/Microsoft/cpprestsdk <home-dir>/cpprestsdk
- Clone the repo and its submodules, and check out the v2.10.19 tag
- Use CMake to configure for your platform
- If you're not familiar with CMake, the CMake GUI may be helpful
- Set the CMake source directory to the Release directory in the cpprestsdk source tree
- Set the CMake build directory to an appropriate location, e.g.
<home-dir>
/cpprestsdk/Release/build
- Set CMake variables to control building C++ REST SDK
- On Windows:
- Set
CPPREST_PPLX_IMPL
(STRING) towinpplx
to solve a performance issue - Set
CPPREST_EXCLUDE_COMPRESSION
(BOOL) to1
(true) to avoid zlib being required - Set
CMAKE_CONFIGURATION_TYPES
(STRING) toDebug;Release
to build only those configurations - Set
Boost_USE_STATIC_LIBS
(BOOL) to1
(true)
- Set
- If CMake cannot find it automatically, set hints for finding Boost, for example:
- Either set
Boost_DIR
(PATH) to the location of the installed BoostConfig.cmake (since Boost 1.70.0) - Or set
BOOST_INCLUDEDIR
(PATH) andBOOST_LIBRARYDIR
(PATH) to the appropriate full paths, e.g.<home-dir>
/boost_1_83_0
and<home-dir>
/boost_1_83_0/x64/lib
respectively to match the suggestedb2
command
- Either set
- Due to interactions with other dependencies, it may also be necessary to explicitly set
WERROR
(BOOL) to0
so that compiler warnings are not treated as errors - To speed up the build by omitting the C++ REST SDK sample apps and test suite, set
BUILD_SAMPLES
andBUILD_TESTS
(BOOL) to0
(false)
- If you're not familiar with CMake, the CMake GUI may be helpful
- Use CMake to generate build/project files, and then build and install
"Visual Studio 14 2015 Win64" and more recent Visual Studio generators have been tested
Windows
For example, for Visual Studio 2019:
cd <home-dir>\cpprestsdk\Release
mkdir build
cd build
cmake .. ^
-G "Visual Studio 16 2019" ^
-DCPPREST_PPLX_IMPL:STRING="winpplx" ^
-DCPPREST_EXCLUDE_COMPRESSION:BOOL="1" ^
-DCMAKE_CONFIGURATION_TYPES:STRING="Debug;Release" ^
-DBoost_USE_STATIC_LIBS:BOOL="1" ^
-DBOOST_INCLUDEDIR:PATH="<home-dir>/boost_1_83_0" ^
-DBOOST_LIBRARYDIR:PATH="<home-dir>/boost_1_83_0/x64/lib" ^
-DWERROR:BOOL="0" ^
-DBUILD_SAMPLES:BOOL="0" ^
-DBUILD_TESTS:BOOL="0"
Then, open and build the INSTALL project in the generated cpprestsdk Visual Studio Solution.
Note: Depending on the current user permissions, Visual Studio may need to be run with administrator privileges in order to install C++ REST SDK.
Or on the Developer command line:
msbuild cpprestsdk.sln /p:Configuration=<Debug-or-Release>
msbuild INSTALL.vcxproj /p:Configuration=<Debug-or-Release>
Note: With the CMake configuration options for C++ REST SDK described above, nmos-cpp apps themselves may need to be run with administrator privileges on Windows.
This is because the C++ REST SDK implementation uses Windows HTTP Services (WinHTTP) by default, which enforces this requirement when using the "*" wildcard to listen on all interfaces.
Administrator privileges are not required if C++ REST SDK is built with CPPREST_HTTP_LISTENER_IMPL
(STRING) set to asio
(and for consistency CPPREST_HTTP_CLIENT_IMPL
(STRING) also set to asio
).
Linux
For example, using the default toolchain and dependencies:
cd <home-dir>/cpprestsdk/Release
mkdir build
cd build
cmake .. \
-DCMAKE_BUILD_TYPE:STRING="<Debug-or-Release>" \
-DWERROR:BOOL="0" \
-DBUILD_SAMPLES:BOOL="0" \
-DBUILD_TESTS:BOOL="0"
make
sudo make install
(To speed up the build, the make -j
option can be used to utilise multiple processor cores, e.g. make -j 4
.)
If using Conan, this section can be skipped.
If not using Conan...
WebSocket++ v0.8.2 (latest release at the time) is included as a submodule within the C++ REST SDK source tree, so a separate installation is not necessary. Note: WebSocket++ v0.5.1 and v0.7.0 have also been tested.
(The Getting Started instructions explain how to set WEBSOCKETPP_INCLUDE_DIR
in order to use the included version when building nmos-cpp.)
If using Conan, this section can be skipped.
If not using Conan...
The C++ REST SDK depends on OpenSSL (to implement secure HTTP and/or secure WebSockets). The nmos-cpp codebase also uses OpenSSL directly to implement the specific requirements of AMWA BCP-003-01 Secure Communication in NMOS Systems and AMWA BCP-003-02 Authorization in NMOS Systems.
OpenSSL version 3 is recommended, and version 3.2.1 (latest release at the time) has been tested. It is currently also possible to use OpenSSL v1.1.1, although this OpenSSL release is now end of life.
- Download and install a recent release
Notes:- On Windows, an installer can be downloaded from Shining Light Productions - Win32 OpenSSL
The Win64 OpenSSL v3.2.1 installer (latest release at the time) has been tested - On Linux distributions, an OpenSSL package may already be available
For example, Ubuntu 22.04 LTS includes OpenSSL v3.0.2
- On Windows, an installer can be downloaded from Shining Light Productions - Win32 OpenSSL
If using Conan, this section can be skipped.
If not using Conan...
A copy of the source code necessary to use this library is supplied in the third_party/nlohmann directory. No installation is necessary.
(The Getting Started instructions explain how to set NMOS_CPP_USE_SUPPLIED_JSON_SCHEMA_VALIDATOR
in order to use the supplied version when building nmos-cpp.)
If using Conan, this section can be skipped.
If not using Conan...
A copy of the source code necessary to use this library is supplied in the third_party/jwt-cpp directory. No installation is necessary.
(The Getting Started instructions explain how to set NMOS_CPP_USE_SUPPLIED_JWT_CPP
in order to use the supplied version when building nmos-cpp.)
Windows
On Windows:
- Download the Bonjour SDK for Windows v3.0 from Apple Developer Downloads
- Run bonjoursdksetup.exe, which will install the necessary files in e.g. C:\Program Files\Bonjour SDK
- The critical files for building this software are:
- Bonjour SDK\Include\dns_sd.h
- Bonjour SDK\Lib\x64\dnssd.lib
- The Bonjour service itself needs to be installed on the system where this software is run
The installer is included in the SDK:- Bonjour SDK\Installer\Bonjour64.msi
Linux
The Avahi project provides a DNS-SD daemon for Linux, and the avahi-compat-libdns_sd library which enables applications to use the original Bonjour dns_sd.h API to communicate with the Avahi daemon.
For example, to install the Bonjour compatibility library, Name Service Switch module, and Avahi tools on Ubuntu:
sudo apt-get install -f libavahi-compat-libdnssd-dev libnss-mdns avahi-utils
Alternatively, Apple's mDNSResponder (also known as mdnsd
) can itself be built from source for Linux. Version 878.200.35 has been tested.
The mDNSResponder
build instructions are quite straightforward. For example, to build and install:
cd mDNSPosix
make os=linux
sudo make os=linux install
(The Getting Started instructions explain how to set NMOS_CPP_USE_AVAHI
(BOOL) to 0
(false) in order to use mDNSResponder
when building nmos-cpp.)
Notes:
- The unicast and permit-over-long-service-types patches found in this repository is recommended to build the
mdnsd
daemon on Linux in order to support unicast DNS-SD.patch -p1 <unicast.patch patch -p1 <permit-over-long-service-types.patch
- The poll-rather-than-select patch found in this repository is recommended to build the
libdns_sd.lib
client-side library to communicate successfully with themdnsd
daemon on Linux hosts where (even moderately) huge numbers of file descriptors may be in use.patch -p1 <poll-rather-than-select.patch
- On systems with IPv6 disabled, the default build of
mdnsd
may immediately stop (when run with-debug
, the errorsocket AF_INET6: Address family not supported by protocol
is reported). Prefixing themake
command above withHAVE_IPV6=0
solves this issue at the cost of repeated warnings from the preprocessor during compilation.
A copy of the single header version (v1.10.0) is supplied in the third_party/catch directory. No installation is necessary.
These instructions explain how to build nmos-cpp itself, run the test suite, and try out the registry and node applications.