Skip to content

Commit fdd6303

Browse files
lalitblalitb
authored
standalone cmake build instructions for opentelemetry-cpp (#612)
1 parent b761ea4 commit fdd6303

File tree

1 file changed

+137
-1
lines changed

1 file changed

+137
-1
lines changed

‎INSTALL.md‎

Lines changed: 137 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,137 @@
1-
# TODO
1+
# Building opentelemetry-cpp
2+
3+
[Bazel](https://bazel.build) and [CMake](https://cmake.org/) are the official
4+
build systems for opentelemetry-cpp.
5+
6+
## Build instructions using CMake
7+
8+
### Prerequisites
9+
10+
- A supported platform (e.g. Windows, macOS or Linux).
11+
Refer to [Platforms Supported](./README.md#supported-development-platforms)
12+
for more information.
13+
- A compatible C++ compiler supporting at least C++11.
14+
Major compilers are supported.
15+
Refer to [Supported Compilers](./README.md#supported-c-versions) for more information.
16+
- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from repository.
17+
To install Git, consult the [Set up Git](https://help.github.com/articles/set-up-git/)
18+
guide on GitHub.
19+
- [CMake](https://cmake.org/) for building opentelemetry-cpp API,
20+
SDK with their unittests. We use CMake version 3.15.2 in our build system.
21+
To install CMake, consult the [Installing CMake](https://cmake.org/install/) guide.
22+
- [GoogleTest](https://github.com/google/googletest) framework to build and
23+
run the unittests.
24+
We use GoogleTest version 1.10.0 in our build system. To install GoogleTest,
25+
consult the [GoogleTest Build Instructions](https://github.com/google/googletest/blob/master/googletest/README.md#generic-build-instructions).
26+
- Apart from above core requirements, the Exporters and Propagators have their
27+
build dependencies which are not covered here. E.g, Otlp Exporter needs
28+
grpc/protobuf library, Zipkin exporter needs nlohmann-json and libcurl,
29+
ETW exporter need nlohmann-json to build. This is covered in the build
30+
instructions for these components.
31+
32+
### Building as Standalone CMake Project
33+
34+
1. Getting the opentelementry-cpp source:
35+
36+
```console
37+
# Change to the directory where you want to create the code repository
38+
$ cd ~
39+
$ mkdir source && cd source
40+
$ git clone https://github.com/open-telemetry/opentelemetry-cpp
41+
Cloning into 'opentelemetry-cpp'...
42+
...
43+
Resolving deltas: 100% (3225/3225), done.
44+
$
45+
```
46+
47+
2. Navigate to the repository cloned above, and create the `CMake`
48+
build configuration.
49+
50+
```console
51+
$ cd opentelemetry-cpp
52+
$ mkdir build && cd build
53+
$ cmake ..
54+
-- The C compiler identification is GNU 9.3.0
55+
-- The CXX compiler identification is GNU 9.3.0
56+
...
57+
-- Configuring done
58+
-- Generating done
59+
-- Build files have been written to: /home/<user>/source/opentelemetry-cpp/build
60+
$
61+
```
62+
63+
Some of the available cmake build variables we can use during
64+
cmake configuration:
65+
66+
- `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` : Please note that with default
67+
configuration, the code is compiled without `-fpic` option, so it is not
68+
suitable for inclusion in shared library. To enable the code for inclusion
69+
in shared libraries, this variable is used.
70+
71+
- `-DWITH_OTLP=ON` : To enable building Otlp exporter.
72+
- `-DWITH_PROMETHEUS=ON` : To enable building prometheus exporter.
73+
74+
3. Once build configuration is created, build the CMake targets -
75+
this includes building SDKs, and building unittests for API and SDK.
76+
Note that since API is header only library, no separate build is triggered for it.
77+
78+
```console
79+
$ cmake --build . --target all
80+
Scanning dependencies of target timestamp_test
81+
[ 0%] Building CXX object api/test/core/CMakeFiles/timestamp_test.dir/timestamp_test.cc.o
82+
[ 1%] Linking CXX executable timestamp_test
83+
...
84+
Scanning dependencies of target w3c_tracecontext_test
85+
[ 99%] Building CXX object ext/test/w3c_tracecontext_test/CMakeFiles/w3c_tracecontext_test.dir/main.cc.o
86+
[100%] Linking CXX executable w3c_tracecontext_test
87+
[100%] Built target w3c_tracecontext_test
88+
$
89+
```
90+
91+
4. Once CMake tests are built, run them with `ctest` command
92+
93+
```console
94+
$ ctest
95+
Test project /tmp/opentelemetry-cpp/build
96+
Start 1: trace.SystemTimestampTest.Construction
97+
...
98+
Start 380: ext.http.urlparser.UrlParserTests.BasicTests
99+
...
100+
100% tests passed, 0 tests failed out of 380
101+
$
102+
```
103+
104+
5. Optionally install the header files for API, and generated
105+
targets and header files for SDK at custom/default install location.
106+
107+
```console
108+
$ cmake --install . --config Debug --prefix /<install_root>/
109+
-- Installing: /<install-root>/lib/cmake/opentelemetry-cpp/opentelemetry-cpp-config.cmake
110+
-- Installing: /<install-root>/lib/cmake/opentelemetry-cpp/opentelemetry-cpp-config-version.cmake
111+
...
112+
-- Installing: /<install-root>/include/opentelemetry//ext/zpages/static/tracez_index.h
113+
-- Installing: /<install-root>/include/opentelemetry//ext/zpages/static/tracez_style.h
114+
-- Installing: /<install-root>/include/opentelemetry//ext/zpages/threadsafe_span_data.h
115+
-- Installing: /<install-root>/lib/libopentelemetry_zpages.a
116+
$
117+
```
118+
119+
### Incorporating Into An Existing CMake Project
120+
121+
To use the library from a CMake project, you can locate it directly with
122+
`find_package` and use the imported targets from generated package
123+
configurations. As of now, this will import targets for both API and SDK.
124+
In future, there may be separate packages for API and SDK which can be
125+
installed and imported separtely according to need.
126+
127+
```cmake
128+
# CMakeLists.txt
129+
find_package(opentelemetry-cpp REQUIRED)
130+
...
131+
target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
132+
target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})
133+
```
134+
135+
## Build instructions using Bazel
136+
137+
TBD

0 commit comments

Comments
 (0)