Adding upstream version 18.2.2.upstream/18.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.