Build OpenTelemetry C++ SDK and exporter into DLL (#1932)

.github/workflows/ci.yml

@@ -518,6 +518,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

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

CHANGELOG.md

@@ -17,6 +17,8 @@ Increment the:
 
 * Convert Prometheus Exporter to Pull MetricReader [#1953](https://github.com/open-telemetry/opentelemetry-cpp/pull/1953)
 * Upgrade prometheus-cpp to v1.1.0 [#1954](https://github.com/open-telemetry/opentelemetry-cpp/pull/1954)
+* [BUILD] Build OpenTelemetry SDK and exporters into DLL
+  [#1932](https://github.com/open-telemetry/opentelemetry-cpp/pull/1932)
 * [CI] Enforce copyright check in CI [#1965](https://github.com/open-telemetry/opentelemetry-cpp/pull/1965)
 * [SEMANTIC CONVENTIONS] Upgrade to version 1.18.0
   [#1974](https://github.com/open-telemetry/opentelemetry-cpp/pull/1974)

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)

INSTALL.md

@@ -264,10 +264,8 @@ cc_library(
 
 ## 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.
+Windows DLL build is supported under **preview**. Please check the
+[doc](./docs/build-as-dll.md) for more details.
 
 ## Generatring binary packages
 

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"
@@ -16,7 +17,7 @@ namespace logs
 /**
  * Creates new Logger instances.
  */
-class LoggerProvider
+class OPENTELEMETRY_EXPORT LoggerProvider
 {
 public:
   virtual ~LoggerProvider() = default;
@@ -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,11 @@
+# Design of building OpenTelemetry C++ SDK and exporters as DLL
+
+**NOTE**: the current build produces a single DLL which includes API, SDK and
+exporters. This **MAY** change in future.
+
+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 an 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)