Building the C++ Client Library for Linux

Building for Linux (x64 only ; 32-bit has not been tested) is supported through Visual Studio’s built-in Linux support.

Prerequisites

  • Microsoft Visual Studio 2017 or greater

  • .Net framework 4.7.1 SDK (needed for our build process automation tools)

  • Linux C++ workload support for Visual Studio (Get it from the Visual Studio Installer)

  • A Linux system (physical, virtual, or WSL) with the build tools of your choice installed

  • libcurl and openssl development packages installed on the Linux system.

This guide will assume you have a working knowledge of how building C++ software on Linux works.

Quick Start

If you haven’t already, follow the instructions to setup the Visual Studio Linux Workload: https://docs.microsoft.com/en-us/cpp/linux/download-install-and-setup-the-linux-development-workload?view=vs-2019

To get the source code of the client library, see Building the C++ Client Library.

If you want to use a different compiler than gcc, a different standard C++ library, or custom-built Curl and/or OpenSSL, see Configuring the Build Process.

Open stormancer-sdk-cpp-141.sln, change the target platform to Linux-x64, and click Build->Build Solution.

The resulting library will be named libStormancer_<Debug|Release>_Linux_x64-gcc.a, provided you have left the build settings to their default values. It will be placed in the folder output/libs (the same as the other platforms).

The Stormancer sample executable will also be built by default. It is a useful indicator as to whether your linker options are correct. If you want to build the library only, right-click the stormancer-sdk-cpp-Linux project in the solution explorer and click Build.

Configuring the Build Process

Firstly, navigate to the root of the Stormancer C++ SDK (the folder that contains stormancer-sdk-cpp-141.sln). Make a copy of the DefaultLinuxBuild.props file, and name this copy CustomLinuxBuild.props.

This CustomLinuxBuild.props file contains settings that you can tweak to customize the build process of the Stormancer client library for Linux. It uses the MSBuild format, but you do not need to be familiar with MSBuild to tweak it.

Let’s take a look at the main options:

<StormancerLinuxToolset>gcc</StormancerLinuxToolset>

This is the name of the build tools stack (compiler, linker, standard C++ library…) you want to use to build Stormancer. It has no effect on the build process itself; rather, it is meant to help you identify the build products. As such, you can set it to anything you want, as long as it does not contain any whitespace or special character.

<OpenSSLIncludeDir></OpenSSLIncludeDir>
<OpenSSLLibDir></OpenSSLLibDir>
<CurlIncludeDir></CurlIncludeDir>
<CurlLibDir></CurlLibDir>

Stormancer on Linux requires Curl and OpenSSL. The easiest way to acquire these dependencies is to install the development packages provided by your Linux distribution. In this case, you should leave these values empty. However, if you want to build stormancer using custom-built Curl and/or OpenSSL instead of the ones provided by your distribution, you should set these values to the corresponding directories on your Linux system where these dependencies’ header files and libraries reside.

<CustomCompilerOptions></CustomCompilerOptions>
<CustomLinkerOptions></CustomLinkerOptions>

Custom options to provide to the compiler and linker.

<RemoteCCompileToolExe>g++</RemoteCCompileToolExe>
<RemoteCppCompileToolExe>g++</RemoteCppCompileToolExe>
<RemoteLdToolExe>g++</RemoteLdToolExe>

These are respectively the C compiler, C++ compiler and linker executables that will be used to build the library. By default, these are all set to g++. So far, the library is known to build with both g++ and clang++.

<RemoteRootDir>$HOME/projects/stormancer-sdk-cpp</RemoteRootDir>

The directory root on the target Linux machine where build will take place.

<StormancerLinuxPropsVersion>2</StormancerLinuxPropsVersion>

This is not a build setting, but rather a version number used internally by the build process to ensure your CustomLinuxBuild.props file is up-to-date. If you update the stormancer library sources, and the format of the DefaultLinuxBuild.props has changed compared to the version you updated from, this number will have been bumped, and so it will not match with the one in your CustomLinuxBuild.props. This will trigger a build failure, prompting you to update your CustomLinuxBuild.props manually, according to the changes in the new DefaultLinuxBuild.props. Once you have updated your CustomLinuxBuild.props, set this number to the same value as the one in the DefaultLinuxBuild.props.

The CustomLinuxBuild.props file also contains other settings beside these, that do not typically need to be adjusted, such as additional include directories, and libraries to link against the Stormancer sample executable. You can still tweak them if you need to.

As with other platforms, you can select Stormancer plugins to be built together with the library. The process is identical, see Plugins.

Examples

Building the library with Clang and libc++:

<PropertyGroup Label="UserMacros">
        <!-- Linux toolset friendly name ; if you change it, also change RemoteCCompileToolExe / RemoteCppCompileToolExe below if needed -->
        <StormancerLinuxToolset>clang</StormancerLinuxToolset>
        <!-- If using non-system-provided Curl or OpenSSL, set these paths to your OpenSSL and Curl libs/include directories (please use absolute paths) -->
        <OpenSSLIncludeDir></OpenSSLIncludeDir>
        <OpenSSLLibDir></OpenSSLLibDir>
        <CurlIncludeDir></CurlIncludeDir>
        <CurlLibDir></CurlLibDir>
        <!-- Custom command-line parameters for the compiler and linker -->
        <CustomCompilerOptions>-stdlib=libc++</CustomCompilerOptions>
        <CustomLinkerOptions>-stdlib=libc++</CustomLinkerOptions>
</PropertyGroup>
<PropertyGroup Condition="'$(TargetPlatformIdentifier)'=='Linux'">
        <!-- Set these to the executable names of your compiler/linker on the target linux machine -->
        <RemoteCCompileToolExe>clang++</RemoteCCompileToolExe>
        <RemoteCppCompileToolExe>clang++</RemoteCppCompileToolExe>
        <RemoteLdToolExe>clang++</RemoteLdToolExe>
</PropertyGroup>

Building the library using custom-built OpenSSL and Curl:

<PropertyGroup Label="UserMacros">
        <!-- Linux toolset friendly name ; if you change it, also change RemoteCCompileToolExe / RemoteCppCompileToolExe below if needed -->
        <StormancerLinuxToolset>gcc</StormancerLinuxToolset>
        <!-- If using non-system-provided Curl or OpenSSL, set these paths to your OpenSSL and Curl libs/include directories (please use absolute paths) -->
        <OpenSSLIncludeDir>/home/user/custom-openssl</OpenSSLIncludeDir>
        <OpenSSLLibDir>/home/user/custom-openssl</OpenSSLLibDir>
        <CurlIncludeDir>/home/user/custom-curl/include</CurlIncludeDir>
        <CurlLibDir>/home/user/custom-curl/lib</CurlLibDir>
        <!-- Custom command-line parameters for the compiler and linker -->
        <CustomCompilerOptions></CustomCompilerOptions>
        <CustomLinkerOptions></CustomLinkerOptions>
</PropertyGroup>
<PropertyGroup Condition="'$(TargetPlatformIdentifier)'=='Linux'">
        <!-- Set these to the executable names of your compiler/linker on the target linux machine -->
        <RemoteCCompileToolExe>g++</RemoteCCompileToolExe>
        <RemoteCppCompileToolExe>g++</RemoteCppCompileToolExe>
        <RemoteLdToolExe>g++</RemoteLdToolExe>
</PropertyGroup>

Using the Library in Your Project

No particular compiler option or flag are required. Just add the client library to your linker’s input, followed by libcurl, libssl and libcrypto, in that order.

Example with g++:

g++ myprogram.cpp -L/path/to/stormancer/lib -pthread -lStormancer_Release_Linux_x64-gcc -lcurl -lssl -lcrypto -ldl

Known issues

HTTP CA certificates

When performing an HTTPS request, Stormancer will always look for certificates at the following paths, in the order they are given:

"/etc/pki/tls/certs/ca-bundle.crt",
"/etc/ssl/certs/ca-certificates.crt",
"/etc/ssl/ca-bundle.pem"

Currently, the is the one and only way certificates are loaded on Linux. The default Curl build-time certificate path is ignored.