1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
# 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:
- FREE [Community Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16)
- [Professional Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Professional&rel=16)
- [Enterprise Edition](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Enterprise&rel=16)
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](https://community.chocolatey.org/packages/visualstudio2019buildtools).
You may also use Visual Studio with Windows 10 Subsystem for Linux to cross-compile
the SDK [targeting Linux distributions](https://code.visualstudio.com/docs/cpp/config-wsl).
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](https://cmake.org/) 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](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019)
is a default build system used by Visual Studio for loading and building software
projects.
[Ninja](https://ninja-build.org/) 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](https://chocolatey.org/) 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](https://vcpkg.io/en/index.html) 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](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-160)
explains the fundamentals of working with CMake projects in Visual Studio.
- Install [Git tools for Windows](https://git-scm.com/downloads).
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`:
- [Google Test](https://github.com/google/googletest)
- [Google Benchmark](https://github.com/google/benchmark)
- [Microsoft GSL](https://github.com/microsoft/GSL)
- [nlohmann/json](https://github.com/nlohmann/json)
- [Abseil](https://github.com/abseil/abseil-cpp)
- [Protocol Buffers](https://github.com/protocolbuffers/protobuf)
- [gRPC](https://github.com/grpc/grpc)
- [Prometheus C++ client](https://github.com/jupp0r/prometheus-cpp)
- [cURL](https://github.com/curl/curl)
## Command Line Build Process
Start `Command Prompt` as Administrator and execute the following commands:
```console
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:
```console
git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp
```
SDK will be cloned recursively with remote submodule dependencies.
```console
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](https://vcpkg.io/en/index.html). 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.
```console
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](https://docs.microsoft.com/en-us/visualstudio/install/build-tools-container?view=vs-2019).
## 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](https://vcpkg.io/en/index.html).
- 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](https://marketplace.visualstudio.com/items?itemName=ChristianSoltenborn.GoogleTestAdapter)
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](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild?view=vs-2019)
vs with [Ninja](https://ninja-build.org/).
[ptime utility](https://community.chocolatey.org/packages/ptime) 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
```console
set CMAKE_GEN=Visual Studio 16 2019
ptime build.cmd
...
Execution time: 543.701 s
```
### Ninja build timing
```console
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.
|
