Skip to content

Latest commit

 

History

History
189 lines (155 loc) · 7.08 KB

INSTALL.md

File metadata and controls

189 lines (155 loc) · 7.08 KB
Raw

Building opentelemetry-cpp

CMake and Bazel are the official build systems for opentelemetry-cpp.

Build instructions using CMake

Prerequisites for CMake

  • A supported platform (e.g. Windows, macOS or Linux). Refer to Platforms Supported for more information.
  • A compatible C++ compiler supporting at least C++11. Major compilers are supported. Refer to Supported Compilers for more information.
  • Git for fetching opentelemetry-cpp source code from repository. To install Git, consult the Set up Git guide on GitHub.
  • CMake for building opentelemetry-cpp API, SDK with their unittests. We use CMake version 3.15.2 in our build system. To install CMake, consult the Installing CMake guide.
  • GoogleTest framework to build and run the unittests. We use GoogleTest version 1.10.0 in our build system. To install GoogleTest, consult the GoogleTest Build Instructions.
  • Apart from above core requirements, the Exporters and Propagators have their build dependencies which are not covered here. E.g, Otlp Exporter needs grpc/protobuf library, Zipkin exporter needs nlohmann-json and libcurl, ETW exporter need nlohmann-json to build. This is covered in the build instructions for each of these components.

Building as Standalone CMake Project

  1. Getting the opentelementry-cpp source:

    # Change to the directory where you want to create the code repository
$ cd ~
$ mkdir source && cd source
$ git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp
Cloning into 'opentelemetry-cpp'...
...
Resolving deltas: 100% (3225/3225), done.
$

  2. Navigate to the repository cloned above, and create the CMake build configuration.

    $ cd opentelemetry-cpp
$ mkdir build && cd build
$ cmake ..
-- The C compiler identification is GNU 9.3.0
-- The CXX compiler identification is GNU 9.3.0
...
-- Configuring done
-- Generating done
-- Build files have been written to: /home/<user>/source/opentelemetry-cpp/build
$

    Some of the available cmake build variables we can use during cmake configuration:

    • -DCMAKE_POSITION_INDEPENDENT_CODE=ON : Please note that with default configuration, the code is compiled without -fpic option, so it is not suitable for inclusion in shared libraries. To enable the code for inclusion in shared libraries, this variable is used.

    • -DWITH_OTLP=ON : To enable building Otlp exporter.

    • -DWITH_PROMETHEUS=ON : To enable building prometheus exporter.

  3. Once build configuration is created, build the CMake targets - this includes building SDKs, and building unittests for API and SDK. Note that since API is header only library, no separate build is triggered for it.

    $ cmake --build . --target all
Scanning dependencies of target timestamp_test
[  0%] Building CXX object api/test/core/CMakeFiles/timestamp_test.dir/timestamp_test.cc.o
[  1%] Linking CXX executable timestamp_test
...
Scanning dependencies of target w3c_tracecontext_test
[ 99%] Building CXX object ext/test/w3c_tracecontext_test/CMakeFiles/w3c_tracecontext_test.dir/main.cc.o
[100%] Linking CXX executable w3c_tracecontext_test
[100%] Built target w3c_tracecontext_test
$

  4. Once CMake tests are built, run them with ctest command

    $ ctest
Test project /tmp/opentelemetry-cpp/build
     Start   1: trace.SystemTimestampTest.Construction
...
     Start 380: ext.http.urlparser.UrlParserTests.BasicTests
...
100% tests passed, 0 tests failed out of 380
$

  5. Optionally install the header files for API, and generated targets and header files for SDK at custom/default install location.

    $ cmake --install . --config Debug --prefix /<install_root>/
-- Installing: /<install-root>/lib/cmake/opentelemetry-cpp/opentelemetry-cpp-config.cmake
-- Installing: /<install-root>/lib/cmake/opentelemetry-cpp/opentelemetry-cpp-config-version.cmake
...
-- Installing: /<install-root>/include/opentelemetry//ext/zpages/static/tracez_index.h
-- Installing: /<install-root>/include/opentelemetry//ext/zpages/static/tracez_style.h
-- Installing: /<install-root>/include/opentelemetry//ext/zpages/threadsafe_span_data.h
-- Installing: /<install-root>/lib/libopentelemetry_zpages.a
$

Incorporating Into An Existing CMake Project

To use the library from a CMake project, you can locate it directly with find_package and use the imported targets from generated package configurations. As of now, this will import targets for both API and SDK. In future, there may be separate packages for API and SDK which can be installed and imported separtely according to need.

# CMakeLists.txt
find_package(opentelemetry-cpp CONFIG REQUIRED)
...
target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})

Build instructions using Bazel

Prerequisites for Bazel

  • A supported platform (e.g. Windows, macOS or Linux). Refer to Platforms Supported for more information.
  • A compatible C++ compiler supporting at least C++11. Major compilers are supported. Refer to Supported Compilers for more information.
  • Git for fetching opentelemetry-cpp source code from repository. To install Git, consult the Set up Git guide on GitHub.
  • Bazel for building opentelemetry-cpp API, SDK with their unittests. We use 3.7.2 in our build system.

To install Bazel, consult the Installing Bazel guide.

Building as Standalone Bazel Project

  1. Getting the opentelementry-cpp source:

    # Change to the directory where you want to create the code repository
$ cd ~
$ mkdir source && cd source
$ git clone https://github.com/open-telemetry/opentelemetry-cpp
Cloning into 'opentelemetry-cpp'...
...
Resolving deltas: 100% (3225/3225), done.
$

  2. Download the dependencies and build the source code:

    $ bazel build //...
bazel build -- //... -//exporters/otlp/... -//exporters/prometheus/...
Extracting Bazel installation...
Starting local Bazel server and connecting to it...
INFO: Analyzed 121 targets (98 packages loaded, 3815 targets configured).
INFO: Found 121 targets...
INFO: From Compiling sdk/src/trace/tracer_context.cc:
...

  3. Once Bazel tests are built, run them with bazel test //... command

    $ bazel test //...
..
$

  4. The build artifacts will be located under bazel-bin