diff options
Diffstat (limited to 'src/jaegertracing/opentelemetry-cpp/INSTALL.md')
| -rw-r--r-- | src/jaegertracing/opentelemetry-cpp/INSTALL.md | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/src/jaegertracing/opentelemetry-cpp/INSTALL.md b/src/jaegertracing/opentelemetry-cpp/INSTALL.md new file mode 100644 index 000000000..69934fde4 --- /dev/null +++ b/src/jaegertracing/opentelemetry-cpp/INSTALL.md @@ -0,0 +1,286 @@ +# Building opentelemetry-cpp + +[CMake](https://cmake.org/) and [Bazel](https://bazel.build) are the official +build systems for opentelemetry-cpp. + +## Dependencies + +You can link OpenTelemetry C++ SDK with libraries provided in +[dependencies.md](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/docs/dependencies.md) +(complete list of libraries with versions used in our CI can be found +[here](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release)). + +## Build instructions using CMake + +### Prerequisites for CMake + +- A supported platform (e.g. Windows, macOS or Linux). Refer to [Platforms + Supported](./README.md#supported-development-platforms) for more information. +- A compatible C++ compiler supporting at least C++11. Major compilers are + supported. Refer to [Supported Compilers](./README.md#supported-c-versions) + for more information. +- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from + repository. To install Git, consult the [Set up + Git](https://help.github.com/articles/set-up-git/) guide on GitHub. +- [CMake](https://cmake.org/) 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](https://cmake.org/install/) guide. +- [GoogleTest](https://github.com/google/googletest) framework to build and run + the unittests. Refer to + [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L5) + for version of GoogleTest used in CI. To install GoogleTest, consult the + [GoogleTest Build + Instructions](https://github.com/google/googletest/blob/master/googletest/README.md#generic-build-instructions). +- [Google Benchmark](https://github.com/google/benchmark) framework to build and + run benchmark tests. Refer to + [third_party_release](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/third_party_release#L4) + for version of Benchmark used in CI. To install Benchmark, consult the + [GoogleBenchmark Build + Instructions](https://github.com/google/benchmark#installation). +- 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: + + ```console + # 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. + + ```console + $ 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. + - `-DBUILD_SHARED_LIBS=ON` : To build shared libraries for the targets. + Please refer to note [below](#building-shared-libs-for-windows) for + Windows DLL support + - `-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. + + ```console + $ 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 + + ```console + $ 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. + + ```console + $ 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. + +```cmake +# 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 + +NOTE: Experimental, and not supported for all the components. Make sure the +[GoogleTest](https://github.com/google/googletest) installation may fail if +there is a different version of googletest already installed in system-defined +path. + +### Prerequisites for Bazel + +- A supported platform (e.g. Windows, macOS or Linux). Refer to [Platforms +Supported](./README.md#supported-development-platforms) for more information. +- A compatible C++ compiler supporting at least C++11. Major compilers are +supported. Refer to [Supported Compilers](./README.md#supported-c-versions) for +more information. +- [Git](https://git-scm.com/) for fetching opentelemetry-cpp source code from +repository. To install Git, consult the [Set up +Git](https://help.github.com/articles/set-up-git/) guide on GitHub. +- [Bazel](https://www.bazel.build/) 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](https://docs.bazel.build/versions/3.7.0/install.html) guide. + +### Building as standalone Bazel Project + +1. Getting the opentelementry-cpp source: + + ```console + # 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. Navigate to the repository cloned above, download the dependencies and build + the source code: + + ```console + $ cd opentelemtry-cpp + $ 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 + + ```console + $ bazel test //... + .. + $ + ``` + +4. The build artifacts will be located under `bazel-bin` + +### Incorporating into an existing Bazel Project + +- WORKSPACE file: + +```console +http_archive( + name = "io_opentelemetry_cpp", + sha256 = "<sha256>", + strip_prefix = "opentelemetry-cpp-1.0.1", + urls = [ + "https://github.com/open-telemetry/opentelemetry-cpp/archive/refs/tags/v1.0.1.tar.gz" + ], +) + +# Load OpenTelemetry dependencies after load. +load("@io_opentelemetry_cpp//bazel:repository.bzl", "opentelemetry_cpp_deps") + +opentelemetry_cpp_deps() + +# Load gRPC dependencies after load. +load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps") + +grpc_deps() + +# Load extra gRPC dependencies due to https://github.com/grpc/grpc/issues/20511 +load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps") + +grpc_extra_deps() + +``` + +- Component level BUILD file: + +```console +cc_library( + name = "<name>" + ... + deps = [ + "@io_opentelemetry_cpp//api", + "@io_opentelemetry_cpp//exporters/otlp:otlp_exporter", + "@io_opentelemetry_cpp//sdk/src/trace", + ... + ], + ... +) +``` + +## Building shared libs for Windows + +Windows DLL build is not supported. There are some constraints on how C++ DLLs +work on Windows, specifically we can't safely allocate memory in one DLL and +free it in another. For now, OpenTelemetry C++ targets need to be statically +linked into the Windows applications. + +## Using Package Managers + +If you are using [Conan](https://www.conan.io/) to manage your dependencies, add +[`opentelemetry-cpp/x.y.z`](https://conan.io/center/opentelemetry-cpp) to your +`conanfile`'s requires, where `x.y.z` is the release version you want to use. +Please file issues [here](https://github.com/conan-io/conan-center-index/issues) +if you experience problems with the packages. + +If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project +for external dependencies, then you can install the [opentelemetry-cpp +package](https://github.com/microsoft/vcpkg/tree/master/ports/opentelemetry-cpp) +with `vcpkg install opentelemetry-cpp` and follow the then displayed +descriptions. Please see the vcpkg project for any issues regarding the +packaging. + +Please note, these packages are not officially provided and maintained by +OpenTelemetry C++ project, and are just listed here to consolidate all such +efforts for ease of developers. |