Build OpenTelemetry C++ SDK and exporter into DLL

.github/workflows/ci.yml

@@ -511,6 +511,23 @@ jobs:
     - name: run otprotocol test
       run: ./ci/do_ci.ps1 cmake.exporter.otprotocol.test
 
+  windows-build-dll:
+    name: CMake -> exporter proto (Build as DLL)
+    runs-on: windows-2019
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+    - name: setup
+      run: |
+        ./ci/setup_windows_cmake.ps1
+        ./ci/setup_windows_ci_environment.ps1
+        ./ci/install_windows_protobuf.ps1
+    - name: run cmake test (DLL build)
+      run: ./ci/do_ci.ps1 cmake.dll.test
+    - name: run otprotocol test (DLL build)
+      run: ./ci/do_ci.ps1 cmake.exporter.otprotocol.dll.test
+
   windows_with_async_export:
     name: CMake (With async export) -> exporter proto
     runs-on: windows-2019

.gitignore

@@ -16,6 +16,7 @@
 *.so
 *.dylib
 *.dll
+*.pdb
 
 # Fortran module files
 *.mod

CHANGELOG.md

@@ -64,6 +64,8 @@ Increment the:
   [#1916](https://github.com/open-telemetry/opentelemetry-cpp/pull/1916)
 * [SEMANTIC CONVENTIONS] Upgrade to version 1.17.0
   [#1927](https://github.com/open-telemetry/opentelemetry-cpp/pull/1927)
+* [BUILD] Build OpenTelemetry SDK and exporters into DLL
+  [#1932](https://github.com/open-telemetry/opentelemetry-cpp/pull/1932)
 * [MAINTAINER DOC] Define and document a deprecation process,
   [DEPRECATION] Deprecate the Jaeger exporter,
   implemented by [#1923](https://github.com/open-telemetry/opentelemetry-cpp/pull/1923)

CMakeLists.txt

@@ -521,6 +521,17 @@ endif()
 
 include(CMakePackageConfigHelpers)
 
+if(DEFINED OPENTELEMETRY_BUILD_DLL)
+  if(NOT MSVC)
+    message(WARNING "Build DLL is supposed to work with MSVC!")
+  endif()
+  if(WITH_STL)
+    message(
+      WARNING "Build DLL with C++ STL could cause binary incompatibility!")
+  endif()
+  add_definitions(-DOPENTELEMETRY_BUILD_EXPORT_DLL)
+endif()
+
 include_directories(api/include)
 
 add_subdirectory(api)

api/include/opentelemetry/baggage/baggage.h

@@ -16,7 +16,7 @@ OPENTELEMETRY_BEGIN_NAMESPACE
 namespace baggage
 {
 
-class Baggage
+class OPENTELEMETRY_EXPORT Baggage
 {
 public:
   static constexpr size_t kMaxKeyValuePairs = 180;

api/include/opentelemetry/common/macros.h

@@ -175,3 +175,28 @@ point.
 #  define OPENTELEMETRY_API_SINGLETON
 
 #endif
+
+/* clang-format on */
+//
+// The if/elif order matters here. If both OPENTELEMETRY_BUILD_IMPORT_DLL and
+// OPENTELEMETRY_BUILD_EXPORT_DLL are defined, the former takes precedence.
+//
+// TODO: consider define OPENTELEMETRY_EXPORT for cygwin/gcc, see below link.
+// https://gcc.gnu.org/wiki/Visibility#How_to_use_the_new_C.2B-.2B-_visibility_support
+//
+#if defined(_MSC_VER) && defined(OPENTELEMETRY_BUILD_IMPORT_DLL)
+
+#  define OPENTELEMETRY_EXPORT __declspec(dllimport)
+
+#elif defined(_MSC_VER) && defined(OPENTELEMETRY_BUILD_EXPORT_DLL)
+
+#  define OPENTELEMETRY_EXPORT __declspec(dllexport)
+
+#else
+
+//
+// build OpenTelemetry as static library or not on Windows.
+//
+#  define OPENTELEMETRY_EXPORT
+
+#endif

api/include/opentelemetry/context/propagation/global_propagator.h

@@ -22,7 +22,7 @@ namespace propagation
 
 /* Stores the singleton TextMapPropagator */
 
-class GlobalTextMapPropagator
+class OPENTELEMETRY_EXPORT GlobalTextMapPropagator
 {
 public:
   static nostd::shared_ptr<TextMapPropagator> GetGlobalPropagator() noexcept

api/include/opentelemetry/context/runtime_context.h

@@ -37,7 +37,7 @@ class Token
  * this class and passing an initialized RuntimeContextStorage object to
  * RuntimeContext::SetRuntimeContextStorage.
  */
-class RuntimeContextStorage
+class OPENTELEMETRY_EXPORT RuntimeContextStorage
 {
 public:
   /**
@@ -78,7 +78,7 @@ static RuntimeContextStorage *GetDefaultStorage() noexcept;
 // Provides a wrapper for propagating the context object globally.
 //
 // By default, a thread-local runtime context storage is used.
-class RuntimeContext
+class OPENTELEMETRY_EXPORT RuntimeContext
 {
 public:
   // Return the current context.

api/include/opentelemetry/logs/logger.h

@@ -323,4 +323,4 @@ class Logger
 }  // namespace logs
 OPENTELEMETRY_END_NAMESPACE
 
-#endif
+#endif  // end of ENABLE_LOGS_PREVIEW

api/include/opentelemetry/logs/logger_provider.h

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 #pragma once
+
 #ifdef ENABLE_LOGS_PREVIEW
 
 #  include "opentelemetry/common/key_value_iterable.h"
@@ -68,4 +69,5 @@ class LoggerProvider
 };
 }  // namespace logs
 OPENTELEMETRY_END_NAMESPACE
-#endif
+
+#endif  // ENABLE_LOGS_PREVIEW

api/include/opentelemetry/trace/noop.h

@@ -27,7 +27,7 @@ namespace trace
 /**
  * No-op implementation of Span. This class should not be used directly.
  */
-class NoopSpan final : public Span
+class OPENTELEMETRY_EXPORT NoopSpan final : public Span
 {
 public:
   explicit NoopSpan(const std::shared_ptr<Tracer> &tracer) noexcept
@@ -76,7 +76,8 @@ class NoopSpan final : public Span
 /**
  * No-op implementation of Tracer.
  */
-class NoopTracer final : public Tracer, public std::enable_shared_from_this<NoopTracer>
+class OPENTELEMETRY_EXPORT NoopTracer final : public Tracer,
+                                              public std::enable_shared_from_this<NoopTracer>
 {
 public:
   // Tracer
@@ -101,7 +102,7 @@ class NoopTracer final : public Tracer, public std::enable_shared_from_this<Noop
 /**
  * No-op implementation of a TracerProvider.
  */
-class NoopTracerProvider final : public opentelemetry::trace::TracerProvider
+class OPENTELEMETRY_EXPORT NoopTracerProvider final : public opentelemetry::trace::TracerProvider
 {
 public:
   NoopTracerProvider() noexcept

api/include/opentelemetry/trace/provider.h

@@ -17,7 +17,7 @@ namespace trace
 /**
  * Stores the singleton global TracerProvider.
  */
-class Provider
+class OPENTELEMETRY_EXPORT Provider
 {
 public:
   /**

api/include/opentelemetry/trace/trace_state.h

@@ -29,7 +29,7 @@ namespace trace
  * For more information, see the W3C Trace Context specification:
  * https://www.w3.org/TR/trace-context
  */
-class TraceState
+class OPENTELEMETRY_EXPORT TraceState
 {
 public:
   static constexpr int kKeyMaxSize         = 256;

api/include/opentelemetry/trace/tracer_provider.h

@@ -13,7 +13,7 @@ namespace trace
 /**
  * Creates new Tracer instances.
  */
-class TracerProvider
+class OPENTELEMETRY_EXPORT TracerProvider
 {
 public:
   virtual ~TracerProvider() = default;

api/test/logs/logger_test.cc

@@ -158,7 +158,7 @@ class TestProvider : public LoggerProvider
                                       bool /* include_trace_context */,
                                       const common::KeyValueIterable & /* attributes */) override
   {
-    return shared_ptr<Logger>(new TestLogger());
+    return nostd::shared_ptr<Logger>(new TestLogger());
   }
 };
 

ci/do_ci.ps1

@@ -51,6 +51,33 @@ switch ($action) {
       exit $exit
     }
   }
+  "cmake.dll.test" {
+    cd "$BUILD_DIR"
+    cmake $SRC_DIR `
+      -DVCPKG_TARGET_TRIPLET=x64-windows `
+      -DOPENTELEMETRY_BUILD_DLL=1 `
+      "-DCMAKE_TOOLCHAIN_FILE=$VCPKG_DIR/scripts/buildsystems/vcpkg.cmake"
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    cmake --build .
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    ctest -C Debug
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    $env:PATH = "$BUILD_DIR\ext\src\dll\Debug;$env:PATH"
+    examples\simple\Debug\example_simple.exe
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+  }
   "cmake.maintainer.test" {
     cd "$BUILD_DIR"
     cmake $SRC_DIR `
@@ -116,6 +143,28 @@ switch ($action) {
       exit $exit
     }
   }
+  "cmake.exporter.otprotocol.dll.test" {
+    cd "$BUILD_DIR"
+    cmake $SRC_DIR `
+      -DVCPKG_TARGET_TRIPLET=x64-windows `
+      -DOPENTELEMETRY_BUILD_DLL=1 `
+      -DWITH_OTPROTCOL=ON `
+      "-DCMAKE_TOOLCHAIN_FILE=$VCPKG_DIR/scripts/buildsystems/vcpkg.cmake"
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    cmake --build .
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    ctest -C Debug
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+  }
   "cmake.exporter.otprotocol.with_async_export.test" {
     cd "$BUILD_DIR"
     cmake $SRC_DIR `

docs/build-as-dll.md

@@ -0,0 +1,8 @@
+# Design of building OpenTelemetry C++ SDK and exporters as DLL
+
+OpenTelemetry C++ can be built into single DLL named opentelemetry_cpp.dll on
+Windows, with CMake flag `OPENTELEMETRY_BUILD_DLL` set to `ON`.
+
+To instrument a application based on the DLL, please define macro
+`OPENTELEMETRY_BUILD_IMPORT_DLL` before including any OpenTelemetry API header
+files in the application source files.

examples/common/foo_library/CMakeLists.txt

@@ -1,6 +1,10 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
+if(DEFINED OPENTELEMETRY_BUILD_DLL)
+  add_definitions(-DOPENTELEMETRY_BUILD_IMPORT_DLL)
+endif()
+
 add_library(common_foo_library foo_library.h foo_library.cc)
 target_link_libraries(common_foo_library PUBLIC ${CMAKE_THREAD_LIBS_INIT}
                                                 opentelemetry_api)

examples/common/logs_foo_library/CMakeLists.txt

@@ -1,6 +1,10 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
+if(DEFINED OPENTELEMETRY_BUILD_DLL)
+  add_definitions(-DOPENTELEMETRY_BUILD_IMPORT_DLL)
+endif()
+
 add_library(common_logs_foo_library foo_library.h foo_library.cc)
 target_link_libraries(common_logs_foo_library PUBLIC ${CMAKE_THREAD_LIBS_INIT}
                                                      opentelemetry_api)

examples/otlp/CMakeLists.txt

@@ -1,43 +1,69 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
+if(DEFINED OPENTELEMETRY_BUILD_DLL)
+  add_definitions(-DOPENTELEMETRY_BUILD_IMPORT_DLL)
+endif()
+
 include_directories(
   ${CMAKE_BINARY_DIR}/generated/third_party/opentelemetry-proto
   ${CMAKE_SOURCE_DIR}/exporters/otlp/include)
 
 if(WITH_OTLP_GRPC)
   add_executable(example_otlp_grpc grpc_main.cc)
-  target_link_libraries(
-    example_otlp_grpc ${CMAKE_THREAD_LIBS_INIT} common_foo_library
-    opentelemetry_trace opentelemetry_exporter_otlp_grpc)
+
+  target_link_libraries(example_otlp_grpc ${CMAKE_THREAD_LIBS_INIT}
+                        common_foo_library)
+
+  if(DEFINED OPENTELEMETRY_BUILD_DLL)
+    target_link_libraries(example_otlp_grpc opentelemetry_cpp)
+  else()
+    target_link_libraries(example_otlp_grpc opentelemetry_trace
+                          opentelemetry_exporter_otlp_grpc)
+  endif()
   if(WITH_LOGS_PREVIEW)
     add_executable(example_otlp_grpc_log grpc_log_main.cc)
-    target_link_libraries(
-      example_otlp_grpc_log
-      ${CMAKE_THREAD_LIBS_INIT}
-      common_logs_foo_library
-      opentelemetry_trace
-      opentelemetry_logs
-      opentelemetry_exporter_otlp_grpc
-      opentelemetry_exporter_otlp_grpc_log)
+
+    target_link_libraries(example_otlp_grpc_log ${CMAKE_THREAD_LIBS_INIT}
+                          common_logs_foo_library)
+    if(DEFINED OPENTELEMETRY_BUILD_DLL)
+      target_link_libraries(example_otlp_grpc_log opentelemetry_cpp)
+    else()
+      target_link_libraries(
+        example_otlp_grpc_log opentelemetry_trace opentelemetry_logs
+        opentelemetry_exporter_otlp_grpc opentelemetry_exporter_otlp_grpc_log)
+    endif()
   endif()
 endif()
 
 if(WITH_OTLP_HTTP)
   add_executable(example_otlp_http http_main.cc)
-  target_link_libraries(
-    example_otlp_http ${CMAKE_THREAD_LIBS_INIT} common_foo_library
-    opentelemetry_trace opentelemetry_exporter_otlp_http)
+
+  target_link_libraries(example_otlp_http ${CMAKE_THREAD_LIBS_INIT}
+                        common_foo_library)
+  if(DEFINED OPENTELEMETRY_BUILD_DLL)
+    target_link_libraries(example_otlp_http opentelemetry_cpp
+                          opentelemetry_common)
+  else()
+    target_link_libraries(example_otlp_http opentelemetry_trace
+                          opentelemetry_exporter_otlp_http)
+  endif()
+
   if(WITH_LOGS_PREVIEW)
     add_executable(example_otlp_http_log http_log_main.cc)
-    target_link_libraries(
-      example_otlp_http_log
-      ${CMAKE_THREAD_LIBS_INIT}
-      common_logs_foo_library
-      opentelemetry_trace
-      opentelemetry_logs
-      opentelemetry_exporter_otlp_http
-      opentelemetry_exporter_otlp_http_log)
+    target_link_libraries(example_otlp_http_log ${CMAKE_THREAD_LIBS_INIT}
+                          common_logs_foo_library)
+
+    if(DEFINED OPENTELEMETRY_BUILD_DLL)
+      target_link_libraries(example_otlp_http_log opentelemetry_cpp
+                            opentelemetry_common)
+    else()
+      target_link_libraries(
+        example_otlp_http_log common_logs_foo_library opentelemetry_trace
+        opentelemetry_logs opentelemetry_exporter_otlp_http
+        opentelemetry_exporter_otlp_http_log)
+    endif()
+
   endif()
 endif()