Corelink CPP Client
Corelink C++ client library
 
Loading...
Searching...
No Matches
Installation

Notes

‍These documents are a work in progress, and we are trying to improve upon them on a daily basis. However, given our capacity and workload, there are bound to be things which get missed or checked in which should not have been checked in. If you find mistakes or documents wanting information, and you would like to help, you can do so in two ways

  1. Submit corrections. When you update anything and submit a PR, we will review it and if all looks good, it will be added. This is the fastest way that one can expect changes to be in.
  2. Submit tickets. If you are not sure how to make updates, or if you are short on time, please raise an issue in the repo, with details and what you think needs to be the expected text. We will try and update the literature to reflect any changes that we feel are merited. Note that this route will take longer than the first approach and there are no guarantees on the timeline.

Dependencies

The current C++ Corelink Client has these direct external dependencies

  • Libwebsockets - Binary installation/ source compilation required
    • Depends further on TLS libraries for Websocket Secure (WSS). Any one of the below are supported.
      • OpenSSL- v1.1.1
      • MbedTLS - Latest
      • LibreSSL - Latest
      • WolfSSL - Latest
  • Asio C++ - Header only library. Used for IP based socket protocols.
  • RapidJSON - Header only library. Used for JSON functionality within the client.

‍On most systems OpenSSL is the recommended TLS library to use. We highly recommend installing OpenSSL from a package manager or downloading the appropriate binaries from the website. However, this is not a possibility for embedded platforms. In this case other choices of TLS libraries from the list can be explored.

Notes about the dependencies

  • All header only libraries are added as a part of the external-dependencies repository.
  • All installable libraries are cross-platform and can be installed using package managers. Alternatively, they can be built from the source itself.

Pre-requisites

The following steps should be generally applicable on any host system .

  • You will need a C++ compiler of your choice which supports C++ 11 or up.
    • On Linux or Mac, you would ideally have g++ or clang++, or both.
    • On Windows, you have the option of using MSVC++, Cygwin, or Mingw. Identify your tool chain well in advance.
    • If you are on Windows and have Visual Studio installed, you will most likely have MSVC++ installed already.
  • These documents assume that you are comfortable using your preferred toolchain. We present examples using CMake as it is the easiest way of demonstrating and compiling source across platforms.
  • There are some platform specific examples for MSVC++ and XCode, which can be found in the examples repository as an addendum, but will not be a focus of this document.

Installing Corelink C++ client dependencies

TLS Library

  • If you wish to enable and use WSS on the client, you will need a compatible TLS library. Please see the list of supported TLS libraries above.
  • You can install these from
    • brew on OSX
    • vcpkg on Windows
    • apt like package managers on Linux
  • These are not the only way you can install these libraries. In many cases, they are shipped with your version of the OS.
  • On *nix style systems (OSX, Linux), these packages will be typically installed in /usr/local or /usr or /opt paths. You will need to keep track of where the package manager installed these for you. The path is typically emitted when you install the libraries.

Libwebsockets

  • Libwebsockets (LWS) is installable just like the TLS libraries above from package managers. We have tested the client to work for version 4.3.x. We do not guarantee API compatibility should you choose to you use another version.
  • You can also build LWS from source by heading over to their GitHub page, and following their instructions.
  • Based on the installation method, you will need to keep track of the path that these libraries were installed under.

Source only header dependencies

The source only dependencies are housed in external-dependencies repository.

However, external dependencies is added as a submodule as part of the corelink client. If you wish to install them this way, see the client installation notes.

You can clone this explicitly.

git clone https://dev.hsrn.nyu.edu/corelink/external-dependencies.git

Some things to note

  • This will fetch all the required source only dependencies required for the client and other components to function.
  • The two libraries that are used from this are ASIO C++ and RapidJSON. There might be other libraries present here, but the client does not use them at the moment. However, examples demonstrating the use of the client might. This does not imply in any way that the client requires them.
  • You will need to identify and keep the paths to the include directories of ASIO C++ and RapidJSON handy.

Corelink Client Installation

You can clone the corelink-clients repo by itself, or, get the dependencies associated with it too.

If you wish to clone the client repo with the source only dependencies.

git clone --recursive --recurse-submodules --remote-submodules https://dev.hsrn.nyu.edu/corelink/corelink-client.git

If you just wish to clone the client repo

git clone https://dev.hsrn.nyu.edu/corelink/corelink-client.git

Building Corelink (optional)

According to your needs (dynamic linking), you may need to build Corelink. We have included a CMakeLists.txt file that can be used to achieve this.

CMake

We set up our CMake toolchain the following way

  • We have a master file CMakeLists.txt which has all the generic parameters which can be shared amongst a group of developers.
  • A user file called CMakeListsUser.txt which has parameters specific to your system and toolchain. This is never shared amongst developers.

If you decide to use the CMakeLists.txt file, you will need to define the following paths to your dependencies:

CORELINK_CPP_STD
CORELINK_ASIO_CPP_PATH
CORELINK_RAPID_JSON_CPP_PATH
CORELINK_LWS_INCLUDE_PATH
CORELINK_OPENSSL_INCLUDE_PATH
CORELINK_LWS_LIB_PATH
CORELINK_OPENSSL_LIB_PATH
CORELINK_OPENSSL_BIN_PATH

This can be done in several ways. We recommend writing a CMakeListsUser.txt file. This file should be placed in the corelink-client/cpp folder.

Below is an example of one such file. If you choose to use this ensure you have updated your paths to point to where the dependencies were installed.

# set the C++ standard we want to use
set(CMAKE_CXX_STANDARD 17)
# set appropriate paths for Libwebsockets to be visible to the compiler
set(CORELINK_LWS_ROOT "C:\\path\\to\\vcpkg\\installed\\x64-windows")
# this is where the header files for LWS reside
set(CORELINK_LWS_INCLUDE_PATH "${CORELINK_LWS_ROOT}\\include")
# this is where the prebuilt binaries for LWS reside
set(CORELINK_LWS_LIB_PATH "${CORELINK_LWS_ROOT}\\lib")
set(CORELINK_LWS_BIN_PATH "${CORELINK_LWS_ROOT}\\bin")
# set the appropriate paths for OpenSSL 1.1.1 to be visible to the compiler
set(CORELINK_OPENSSL_ROOT"C:\\path\\to\\vcpkg\\installed\\x64-windows")
# this is where the header files for OpenSSL reside
set(CORELINK_OPENSSL_INCLUDE_PATH "${CORELINK_OPENSSL_ROOT}\\include")
# this is where the prebuilt binaries for OpenSSL reside
set(CORELINK_OPENSSL_LIB_PATH "${CORELINK_OPENSSL_ROOT}\\lib")
set(CORELINK_OPENSSL_BIN_PATH "${CORELINK_OPENSSL_ROOT}\\bin")
# Set the appropriate paths for external source only dependencies
set(CORELINK_ASIO_CPP_PATH C:\\path\\to\\corelink-client\\external-dependencies\\cpp\\asio-cpp\\v1.24.0\\‍)
set(CORELINK_RAPID_JSON_CPP_PATH C:\\path\\to\\corelink-client\\external-dependencies\\cpp\\‍)

Once you have correctly defined the paths, you can take the following steps to build the Corelink CPP client using CMake:

cd /path/to/corelink-client/cpp/
cmake -B client-build-debug -S .
cmake --build client-build-debug

Closing remarks

  • As you can gather from the steps above, the "installation" is merely downloading or installing things from package managers or git repositories.
  • These steps have been reproduced on OSX, Mainstream Linux distributions, and Windows systems. In theory, these should work just fine on any system, if you use a standard C++ compiler.