Setup Examples

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.

PLEASE NOTE: Corelink can be set up in many ways, and according to your needs, the below examples may not apply.

We cannot provide setup instructions for every single potential application of Corelink, however we have provided an examples repository with some to help you get started.

A brief review of installed items

• The installation document enumerates the things that one needs to "install"
  • A TLS library
  • Libwebsockets (LWS)
  • Corelink Client
  • Corelink Source Only external dependencies.

Items of consequence

• For source only libraries, you can trivially point your toolchain to point to the paths where these libraries reside. Post that, you should be able to simply #include them in your application/ library.
• For libraries installed via package managers which have pre-built dynamic/ static binaries, you will need to identify a couple of paths
  1. Where their header files reside, as this will allow you to include them and target them in your application
  2. Where their library binaries reside. This is so that the linker can search for appropriate binaries and for runtime resolution.
  3. Which libraries are you targeting so that the linker knows which binaries to target in the paths specified in step 2.

Including as Source

In order to include Corelink directly into your project as source code, you must point your compiler/project to Corelink's include and src directories. The steps to do this are below for XCode, CMake, and MSFT Visual Studio.

Including as DLL

In order to include Corelink as a DLL, you must first build it. In this case, Corelink will become a third-party dependency for your project.

Building Corelink

We have included a CMakeLists.txt file that can be used to build Corelink. It should be located in the corelink-client/cpp directory.

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

You should now have a directory in your corelink-client directory called client-build-debug.

Including Dependency Directories

We have provided a few examples on how to set up dependency paths below. We first must make sure that all the paths to dependency bin/ and lib/ directories are available at runtime.

The way we recommend to do this is to add the paths to your PATH% variable (Windows) or $PATH (MacOS/Linux).

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.

Below are the contents of a sample CMakeLists.txt file for an OSX system.

‍NB: This is just a sample file and the paths here could be different from the one on your system. Please do not raise tickets or issues to correct or fix these.

####
# Author : Sarthak Tickoo (NYU IT HSRN)
####
 
# specify the minimum cmake version required.
cmake_minimum_required(VERSION 3.1)
 
# specify a name for your project. this can be anything
project(corelink-examples VERSION 0.1.0
        LANGUAGES C CXX)
 
# this piece of script tries to locate the user file on your system
# note that this looks for the user file in the project directory which typically is the directory this master 
# file resides in
if (EXISTS "${PROJECT_SOURCE_DIR}/CMakeListsUser.txt")
    include("${PROJECT_SOURCE_DIR}/CMakeListsUser.txt")
endif ()
 
# make sure that you force the specification of a C++ standard.
# minimum is 11. this will be set as a part of the user file
set(CMAKE_CXX_STANDARD_REQUIRED True)
 
# specify the target name as a variable
set(TEST basic-connect-test)
 
# prepare the target for build. this is where all your C++ header and source files go if you want to compile them
add_executable(${TEST} basic-connect-test.cpp)
 
# force treatment of warnings as errors. this saves lives. trust me.
target_compile_options(${TEST} PRIVATE
        $<$<CXX_COMPILER_ID:MSVC>:/W4 /WX>
        $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Wpedantic -Werror -Wno-deprecated-declarations>
        )
# Add the include paths that are needed
# the first path is the path to corelink c++ library itself
# the rest of the paths are defined as variables in the user file.
target_include_directories(${TEST}
        PUBLIC "${CORELINK_INCLUDE_DIR}" # Only needed if including as source
        PUBLIC "${CORELINK_ASIO_CPP_PATH}"
        PUBLIC "${CORELINK_RAPID_JSON_CPP_PATH}"
        PUBLIC "${CORELINK_LWS_INCLUDE_PATH}"
        PUBLIC "${CORELINK_OPENSSL_INCLUDE_PATH}"
        )
 
 
# Only needed if including as source:
# Add the source files for Corelink 
file(GLOB_RECURSE CORELINK_SOURCES "${CORELINK_SRC_DIR}/*.cc") 
# Add Corelink source files to the test target 
target_sources(${TEST} PRIVATE ${CORELINK_SOURCES})
 
# Add the paths for libraries to be linked
target_link_directories(${TEST}
        PUBLIC "${CORELINK_LWS_LIB_PATH}"
        PUBLIC "${CORELINK_LWS_BIN_PATH}"
        PUBLIC "${CORELINK_OPENSSL_LIB_PATH}"
        PUBLIC "${CORELINK_OPENSSL_BIN_PATH}"
        )
 
# set the dynamic library extension and prefix. This is dumb but works for now.
set(DYNA_LIB_EXT so)
set(LWS_PREFIX lib)
if (APPLE)
    set(DYNA_LIB_EXT dylib)
endif (APPLE)
if (WIN32)
    set(DYNA_LIB_EXT dll)
    set(LWS_PREFIX "")
endif (WIN32)
# specify which libraries need to be linked against our target
target_link_libraries(${TEST}
        ${LWS_PREFIX}websockets.${DYNA_LIB_EXT}
        libssl.${DYNA_LIB_EXT}
        libcrypto.${DYNA_LIB_EXT})

Below are the contents of a sample CMakeListsUser.txt file for an OSX system.

# set the C++ standard we want to use
set(CMAKE_CXX_STANDARD 11)
 
set(CORELINK_SRC_DIR) "/Users/sarthak/Work/hsrn/corelink/repos/corelink-client/cpp/src/"
set(CORELINK_INCLUDE_DIR) "/Users/sarthak/Work/hsrn/corelink/repos/corelink-client/cpp/include/"
# set appropriate paths for Libwebsockets to be visible to the compiler
set(CORELINK_LWS_ROOT "/opt/homebrew/Cellar/libwebsockets/4.3.2")
# 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 "/opt/homebrew/Cellar/openssl@1.1/1.1.1s")
# 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 ~/Work/hsrn/corelink/repos/external-dependencies/cpp/asio-cpp/v1.24.0/)
set(CORELINK_RAPID_JSON_CPP_PATH ~/Work/hsrn/corelink/repos/external-dependencies/cpp/)

MSFT Visual Studio

Setting up C++ version

Setting up Header Paths

Setting up library paths

If you are dynamically linking, you would also place the path to your .../corelink-client/cpp/client-build-debug/Debug/lib and .../Debug/bin directory here.

If you are including as source, you would place the path to your .../corelink-client/cpp/src directory here. You will also need to manually add the source files to your project by right-clicking the Source Files folder in Solution Explorer → Add → Existing Item → select all source files from Corelink's src folder.

Setting up library names to link

If you are dynamically linking, you would also place corelinkclient.lib here.

Apple Xcode

You can achieve a similar setup on XCode.

‍Please note that some of these settings can vary on your system. These are decided by your application and are just meant to serve as a template not as a definitive solution

#### Setting up C++ version

Searching for Paths

Setting up Header Paths

Setting up library paths

If you are dynamically linking, you would also place the path to your .../corelink-client/cpp/client-build-debug/Debug directory here.

If you are including as source, you would place the path to your .../corelink-client/cpp/src directory here. You will also need to manually add the source files to your project. In the Project Navigator, right-click your project folder, select Add Files to "YourProject", and select all source files from Corelink's src directory.

Setting up library names to link

If you are dynamically linking, you would also place corelinkclient.lib here.

Using Corelink Client with your application

This is a brief introduction on how to include Corelink library in your project after you have followed the steps above to set up the paths and libraries appropriately.

Including Corelink

To include Corelink, just include corelink_all.hpp in your project like so

#include "corelink_all.hpp"

Alternatively, if quotes don't work, replace them with angled brackets

#include <corelink_all.hpp>

Enabling features

Corelink library by default turns off a few features to save you some on the binary size and the feature set. You can choose to manually enable features one by one, or, simply define the following macros as:

#define CORELINK_ENABLE_ALL_FEATURES
#define CORELINK_USE_CONCURRENT_QUEUE
#define CORELINK_USE_UDP
#define CORELINK_USE_TCP
#define CORELINK_USE_WEBSOCKET

Tying it up

To do this correctly, you need to define this macro above the include statement. So the correct sequence of statements would be

// enable all features by defining this macro
#define CORELINK_ENABLE_ALL_FEATURES
#define CORELINK_USE_CONCURRENT_QUEUE
#define CORELINK_USE_UDP
#define CORELINK_USE_TCP
#define CORELINK_USE_WEBSOCKET
// C++ compiler will see this macro above and then expand all the necessary items
#include <corelink_all.hpp>

Closing remarks

This concludes a guide on how you can include Corelink C++ client to be used in your application. This is by no means an exhaustive all-inclusive guide. You are free to chose your own tool chain as long as basic requirements are met.