open-telemetry
/
opentelemetry-cpp
mirror of https://github.com/open-telemetry/opentelemetry-cpp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
opentelemetry-cpp/docs/building-with-vs2019.md

8.1 KiB
Raw Permalink Blame History

Building OpenTelemetry C++ SDK with Visual Studio 2019, CMake and Ninja

Preface

These instructions are focused on developers and integrators, providing a hassle-free and FAST option of building OpenTelemetry C++ SDK with Visual Studio on Windows.

The process is optimized for both scenarios:

  • SDK developer experience on developer machine.
  • final product CI/CD pipeline.

Build System Components

Visual Studio 2019 is a Full-featured integrated development environment (IDE) for Android, iOS, Windows, web, and cloud. There are three editions:

There is also no-IDE 'headless' set of command line tools available as Visual Studio 2019 Build Tools package. You may install it on Windows via Chocolatey package manager.

You may also use Visual Studio with Windows 10 Subsystem for Linux to cross-compile the SDK targeting Linux distributions. Linux build process is largely identical to Windows process described below, with tools/setup-buildtools.sh and tools/build.sh running on Linux.

Older versions of Visual Studio, such as 2015 and 2017 are known to work well with CMake and Ninja. However, these old versions are not covered by instructions below. If you would like to contribute additional instructions for older versions, feel free to contribute a Pull Request detailing your build experience with older versions.

CMake is cross-platform free and open-source software for build automation, testing, packaging and installation of software by using a compiler-independent method. CMake is not a build system but rather it generates another system's build files.

MSBuild is a default build system used by Visual Studio for loading and building software projects.

Ninja is a small build system with a focus on speed. It differs from other build systems in two major respects: it is designed to have its input files generated by a higher-level build system, and it is designed to run builds as fast as possible.

Chocolatey package manager has the largest online registry of Windows packages. Chocolatey packages encapsulate everything required to manage a particular piece of software into one deployment artifact by wrapping installers, executables, zips, and/or scripts into a compiled package file.

vcpkg is a free C/C++ package manager for acquiring and managing libraries. Choose from over 1500 open source libraries to download and build in a single step or add your own private libraries to simplify your build process. Maintained by the Microsoft C++ team and open source contributors.

Installing Prerequisites

Please install the following software:

  • Install Visual Studio 2019 with C/C++ development tools, including CMake tools. This article explains the fundamentals of working with CMake projects in Visual Studio.

  • Install Git tools for Windows.

Setup script below uses Chocolatey to install the following components:

  • vswhere - utility to auto-discover Visual Studio installation.
  • cmake
  • git
  • vcpkg to download, compile and install 3rd party C++ libraries from source.

List of C++ dependencies compiled and installed via vcpkg:

Command Line Build Process

Start Command Prompt as Administrator and execute the following commands:

git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp
cd opentelemetry-cpp
tools\setup-buildtools.cmd
tools\build.cmd

Let's dissect the flow:

git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp

SDK will be cloned recursively with remote submodule dependencies.

cd opentelemetry-cpp
tools\setup-buildtools.cmd

The necessary build tools are installed. This step requires elevation to install additional tooling, e.g. CMake to Program Files. The necessary dependencies are being built using vcpkg package manager. This one-time step is time-consuming - about up to 5-10 minutes. It has to be done once during the initial installation and configuration of build tools and dependencies.

tools\build.cmd

The build of all SDK components is done using CMake + ninja in less than couple minutes. Above script shows you how to build both configurations:

  • nostd - OpenTelemetry implementation of standard containers.
  • stdlib - Standard Template Library containers.

You may execute this workflow in a docker container. Please refer to generic instructions that detail how to run build build tools in a docker container.

Building in Visual Studio 2019 IDE

  • Run as Administrator: tools\setup-buildtools.cmd to install the necessary build tooling. This script installs all build tools and builds all 3rd party dependencies from source using vcpkg package manager.
  • Launch Visual Studio 2019 IDE.
  • Use Open a local folder option to open the folder where you cloned the source code.
  • Right-click on CMakeLists.txt and choose Generate Cache for opentelemetry-cpp.
  • In the top bar menu - select Build -> Build All to build SDK, Exporters and Tests.
  • You can use Google Test Adapter Visual Studio extension to run all SDK and Exporter tests in IDE.
  • You can individually select and run only given tests or examples.

Visual Studio provides an excellent debugging and troubleshooting experience, with incremental builds using Ninja typically taking just one click to build and less than a few seconds for the build to complete.

Build time comparison between MSBuild and Ninja

After the initial set of 3rd party dependencies have been built via tools\setup-buildtools.cmd, we can benchmark the OpenTelemetry C++ SDK build times with MSBuild vs with Ninja.

ptime utility may be used to measure the total execution time for two build configurations built in one run: nostd-debug and stdlib-debug.

MSBuild build timing

set CMAKE_GEN=Visual Studio 16 2019
ptime build.cmd
...
Execution time: 543.701 s

Ninja build timing

REM Unset CMAKE_GEN= - default is ninja with autodetection of ninja.exe tool path
set CMAKE_GEN=
ptime build.cmd
...
Execution time: 105.158 s

Conclusion

It is strongly recommended to build the SDK with Ninja since it is at least x5 times faster than MSBuild for a full clean build. Incremental builds with Ninja are also considerably faster. Each incremental build is taking about 10 seconds total for 2 build configurations. Absolute time may differ depending on machine being benchmarked. Relative ratio on most machines demonstrates that building with Ninja build system greatly optimizes your development cycle. Not only it saves your development time, optimizes your CI/CD cycle, but it is also much more environmentally friendly.